---
title: "Get Time Entries"
method: GET
path: "/v1/time-entries"
tags: ["time-entries"]
---

# Get Time Entries

`GET /v1/time-entries`

## Request

- Base URL: `https://app.tokumalabs.com/api`
- URL: `https://app.tokumalabs.com/api/v1/time-entries`
- Auth: OAuth 2
  - Password
  - Token URL: `v1/auth/token`

Get time entries for the specified date.

## Query parameters

- `date` string, date, required: Date to get time entries for (YYYY-MM-DD)

## Response `200`

Successful Response

- TimeEntryListResponse: Response model for a list of time entries.
  - `time_entries` TimeEntryDto[], required: List of time entries for the specified date
    - `id` string, required: Unique identifier of the time entry
    - `date` string, date, required: The date this entry belongs to
    - `narrative` string, nullable: Human-readable description of the time entry. NULL while a multi-stage generation is between the Segment commit (skeleton row created) and the Narrate fill-in for this entry — the desktop client renders a Skeleton component until the narrative lands.
    - `narrative_suggestions` string[], nullable: AI-generated narrative alternatives
    - `activity_code` string, nullable: Code of the activity
    - `matter_segment` MatterSegmentSummaryDto: Summary of matter and segment for time blocks.
      - `matter_id` string, required: Matter ID
      - `matter_name` string, required: Matter name
      - `segment_id` string, required: Segment ID
      - `segment_name` string, required: Segment name
      - `segment_order` integer, required: Display order of the segment within the matter
      - `is_root` boolean, required: Whether this is the root segment
      - `root_segment_id` string, nullable: Root segment ID of the matter
    - `is_billable` boolean, required: Whether the time entry is billable
    - `is_released` boolean: Whether the time entry has been released
    - `released_at` string, date-time, nullable: When the time entry was released
    - `legal_time_minutes` integer, required: Legal time in minutes. Computed from tracked_duration_minutes and the matter's billing rounding unless a person typed it or the entry is released — legal_time_is_computed says which.
    - `legal_time_is_computed` boolean, required: True when legal_time_minutes was computed from tracked time and the matter's billing rounding, False when it is a stored figure (typed by a person, or frozen at release).
    - `tracked_duration_minutes` integer, required: Actual tracked time in minutes (sum of block durations without overlaps)
    - `legal_time_pinned` boolean: True iff legal_time_minutes was typed by a person (manual create or an API PATCH that supplied legal_time_minutes), False iff it is computed. Gates the regen sweep's manual-entry preservation. Cleared by a PATCH sending legal_time_minutes: null.
    - `legal_time_resnapped_from` integer, nullable: The typed legal time this entry held immediately before a move re-rounded it onto another matter's billing rounding, or null when nothing has. Presentation only — legal_time_minutes is already the figure. When it clears is stated once, on the TimeEntry model column
    - `is_user_created` boolean: True iff a person created this entry through the API — the manual Add-entry dialog, or the drag that files captured blocks into a new entry. False for generation output. Read by the desktop's rebuild warning so its impact counts match the server's preserved set.
    - `created_at` string, date-time, required: When the time entry was created
    - `updated_at` string, date-time, required: When the time entry was last updated

## Other responses

- `400`: Validation error or domain rule violation.
- `401`: Missing, expired, or invalid authentication.
- `403`: Authenticated but not permitted.
- `404`: Resource not found.
- `409`: Resource state conflict (duplicate, illegal transition).
- `422`: Request body failed schema validation.
- `500`: Server-side failure.

---

[API](https://skmtc.dev/tokumalabs/apis/tokuma-user-api.md) - [All operations](https://skmtc.dev/tokumalabs/apis/tokuma-user-api/llms.txt) - [OpenAPI document](https://skmtc.dev/tokumalabs/apis/tokuma-user-api/revisions/1f8201af459b?raw)