> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lala.ist/llms.txt
> Use this file to discover all available pages before exploring further.

# Study time over a date range

> Completed planner minutes, summed. `days` carries every date in the range, zeros
included, so a heatmap renders straight off it. `bySubject` is the distribution the
treemap shows, with each share of the total.

Both dates are local Istanbul dates and the range is capped at 366 days —
an aggregate over a year is one bounded read, so there is no cursor.

`dailyAvgMin` averages over the days with any completed work, not the calendar: it
answers "how much does a study day hold", not "how thin does the month spread".



## OpenAPI

````yaml /api-reference/openapi.json get /api/journey/study
openapi: 3.1.0
info:
  title: Lala Client API
  description: >-
    The HTTP API behind Lala, the AI study companion for Turkish YKS and LGS
    students. This document is generated from the Zod schemas that validate each
    request at runtime. Do not hand-edit openapi.json. Student-visible text is
    Turkish. All identifiers are English.
  version: 1.0.0
servers:
  - url: https://client-api.lala.ist
    description: production
  - url: http://localhost:3000
    description: local dev
security:
  - supabaseJwt: []
tags:
  - name: chat
    description: The chat stream, the message history, and reactions
  - name: media
    description: Upload and read message attachments
  - name: plan
    description: The study planner — blocks of work on a day
  - name: journey
    description: Deneme results, topic performance, study-hours stats, and the streak
  - name: profile
    description: The student profile and onboarding
  - name: devices
    description: Push notification devices
  - name: system
    description: Health check
paths:
  /api/journey/study:
    get:
      tags:
        - journey
      summary: Study time over a date range
      description: >-
        Completed planner minutes, summed. `days` carries every date in the
        range, zeros

        included, so a heatmap renders straight off it. `bySubject` is the
        distribution the

        treemap shows, with each share of the total.


        Both dates are local Istanbul dates and the range is capped at 366 days
        —

        an aggregate over a year is one bounded read, so there is no cursor.


        `dailyAvgMin` averages over the days with any completed work, not the
        calendar: it

        answers "how much does a study day hold", not "how thin does the month
        spread".
      operationId: getApiJourneyStudy
      parameters:
        - in: query
          name: from
          schema:
            type: string
          required: true
          description: Local Istanbul date, `YYYY-MM-DD`.
        - in: query
          name: to
          schema:
            type: string
          required: true
          description: Local Istanbul date, inclusive. At most 366 days.
      responses:
        '200':
          description: The study stats
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StudyStatsResponse'
        '400':
          description: The input is not valid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The token is missing, expired, or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    StudyStatsResponse:
      type: object
      properties:
        from:
          type: string
        to:
          type: string
        days:
          type: array
          items:
            $ref: '#/components/schemas/StudyDayStat'
          description: >-
            Every date in the range, zero days included — a heatmap renders off
            it.
        bySubject:
          type: array
          items:
            $ref: '#/components/schemas/StudySubjectStat'
          description: Largest first.
        totalMin:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        activeDays:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        dailyAvgMin:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
      required:
        - from
        - to
        - days
        - bySubject
        - totalMin
        - activeDays
        - dailyAvgMin
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        issues:
          description: >-
            Present only on a 400 raised by request validation, capped at 10
            entries. Every other error carries `error` alone.
          type: array
          items:
            $ref: '#/components/schemas/ValidationIssue'
      required:
        - error
      description: Error body. `error` is a short English string.
    StudyDayStat:
      type: object
      properties:
        date:
          type: string
        minutes:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
      required:
        - date
        - minutes
    StudySubjectStat:
      type: object
      properties:
        subject:
          type: string
          description: The planner's display subject, as stored.
        minutes:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        pct:
          type: number
          description: Share of the range total, 0–100.
      required:
        - subject
        - minutes
        - pct
    ValidationIssue:
      type: object
      properties:
        path:
          type: string
          description: Dotted path to the offending field, empty at the root.
        message:
          type: string
      required:
        - path
        - message
  securitySchemes:
    supabaseJwt:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Supabase access token: `Authorization: Bearer <token>`'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.