> ## Documentation Index > Fetch the complete documentation index at: https://superthread.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # List or aggregate time entries > Returns a paginated list of time entries within a workspace, optionally filtered by scope, user, time range, or billable flag. When `aggregate=true` and `group_by` is supplied, returns aggregated totals grouped by the specified dimension instead of the entry list. The same filters apply. ## OpenAPI ````yaml GET /{team_id}/time/entries openapi: 3.0.0 info: description: Superthread Public API Specification version: '0.1' title: Public API contact: email: engineering@superthread.com servers: - url: https://api.superthread.com/v1 security: - BearerAuth: [] tags: - name: AI description: >- [Service: AI]. Handles AI-powered functionalities, such as recommendations, predictions, and automation features. - name: Activity description: >- [Service: Activity] Manages all activities; creating notifications and digests - name: Auth description: >- [Service: Auth] Responsible for user authentication, authorization, and session management. - name: Boards description: >- [Service: Boards] Manages core collaboration features such as "boards", "cards", "lists", "sprints", "epics". - name: Comments description: >- [Service: Comments] Handles the creation, editing, and management of comments across various entities. - name: Favourites description: >- [Service: Favourites] Responsible for favouriting resources in the system for quick access. - name: Files description: >- [Service: Files] Manages file uploads, storage, and retrieval for user and project resources. - name: Importer description: >- [Service: Importer] Handles data import operations from external sources into the platform. - name: Integrations description: >- [Service: Integrations] Facilitates connectivity with external tools and services, enabling smooth integration with third-party platforms and APIs. - name: Pages description: >- [Service: Pages] Manages the creation and organization of both public and private pages, supporting structured content and navigation and collaboration. - name: Projects description: '[Service: Projects] Handles all project related tasks.' - name: Reports description: >- [Service: Reports] Generates and manages analytical reports and insights for users and projects. - name: Search description: >- [Service: Search] Provides search functionalities, including indexing and retrieval of platform data. - name: TimeTracking description: >- [Service: TimeTracking] Manages time entries, active timers, time categories, billing rates, and audit/lock for time-tracking workflows. - name: Views description: >- [Feature] Provides tools to create and customize views, enabling users to organize and visualize their data according to their preferences and workflows. - name: OAuth2 description: >- [Feature] Supports OAuth2 integration for seamless user authentication and authorization, ensuring secure access to external APIs and services. - name: Sprints description: >- [Feature] Facilitates sprint management within agile workflows, including planning, progress tracking, and reporting. - name: Cards description: >- [Feature] A Card is the core concept used in the system to describe an individual task or work item. They are used across Boards, Sprints, and Roadmaps. Cards include features like descriptions, checklists, comments, priorities, tags and more. - name: Checklists description: >- [Feature] A Checklist is a list of items that need to be completed. It is used to track progress on a card. - name: Lists description: >- [Feature] Represents a collection of tasks or items grouped within different contexts in the system. Lists (externally referenced as "statuses") are utilized across various entities such as boards, sprints, and roadmaps. - name: Notes description: >- [Feature] Enables users to create, edit, and organize notes, supporting rich text, attachments, transcriptions and AI enhancements. - name: Tags description: >- [Feature] Groups endpoints related to the creation, retrieval, updating, deletion, and merging of tags within teams (workspaces). - name: Agents description: >- [Feature] Manages agents and runs. Provides CRUD operations for agents, launching cloud agents, monitoring agent status, retrieving conversations, and sending follow-ups. paths: /{team_id}/time/entries: parameters: - $ref: '#/components/parameters/path_team_id' get: tags: - TimeTracking summary: List or aggregate time entries description: > Returns a paginated list of time entries within a workspace, optionally filtered by scope, user, time range, or billable flag. When `aggregate=true` and `group_by` is supplied, returns aggregated totals grouped by the specified dimension instead of the entry list. The same filters apply. operationId: getTimeEntries parameters: - in: query name: scope_type description: Filter to entries with this scope type. required: false schema: type: string enum: - card - category - in: query name: scope_id description: >- Filter to entries with this scope id (typically used together with `scope_type`). required: false schema: type: string - in: query name: user_id description: Filter to entries logged by this user. required: false schema: type: string - in: query name: from description: >- Lower bound (inclusive) for `started_at`, as a unix timestamp in seconds. required: false schema: type: integer format: int64 - in: query name: to description: >- Upper bound (exclusive) for `started_at`, as a unix timestamp in seconds. required: false schema: type: integer format: int64 - in: query name: billable description: Filter to billable (true) or non-billable (false) entries. required: false schema: type: boolean - in: query name: cursor description: Pagination cursor returned by a previous call. required: false schema: type: string - in: query name: limit description: Page size; defaults to a server-defined value. required: false schema: type: integer - in: query name: aggregate description: >- When `true`, return aggregated buckets (`buckets`, `group_by`) instead of the entry list. Requires `group_by`. required: false schema: type: boolean - in: query name: group_by description: >- Dimension to group aggregate buckets by. Required when `aggregate=true`. required: false schema: type: string enum: - user - scope - week - billable responses: '200': description: > Paginated list of time entries, or aggregated buckets when `aggregate=true`. content: application/json: schema: $ref: '#/components/schemas/GetTimeEntriesOrAggregateResponse' default: description: client error content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/Error' components: parameters: path_team_id: in: path name: team_id description: >- Team ID is an alphanumerical string that identifies a Team. This is externally referred to as a "Workspace". required: true schema: type: string schemas: GetTimeEntriesOrAggregateResponse: type: object description: > Composite response for `GET /{team_id}/time/entries`. When `aggregate` is not set, the response carries `time_entries` (plus paging fields from `ResponseMetadata`); when `aggregate=true`, the response carries `buckets` and `group_by`. All fields are optional because OpenAPI 2.0 cannot express a `oneOf` cleanly. allOf: - $ref: '#/components/schemas/ResponseMetadata' properties: time_entries: type: array items: $ref: '#/components/schemas/TimeEntry' x-omitempty: true group_by: type: string enum: - user - scope - week - billable x-omitempty: true buckets: type: array items: $ref: '#/components/schemas/TimeEntryAggregateBucket' x-omitempty: true Error: type: object properties: id: type: string example: err5f744ab code: type: integer format: int32 example: 403 sec: $ref: '#/components/schemas/SuperthreadErrorCode' message: type: string example: You do not have access to this resource description: A user-friendly error message date: $ref: '#/components/schemas/STime' ResponseMetadata: type: object required: - cursor - count properties: cursor: type: string example: dmsjqh9d8w1hdjosjaasda nullable: false count: type: integer example: 14 nullable: false TimeEntry: type: object properties: id: type: string description: Client-supplied ULID. example: 01HQK6Z9YJZ4M9JX8FVB6QXYAB type: type: string example: time_entry team_id: type: string example: tDsu0j19 scope_type: $ref: '#/components/schemas/TimeEntryScopeType' scope_id: type: string description: ID of the card or time category this entry is logged against. example: '2700' user_id: type: string example: uR2dws11 started_at: $ref: '#/components/schemas/STime' duration_seconds: type: integer format: int64 description: Duration of the entry in seconds. example: 1800 description: type: string description: Optional free-text note. example: Pairing with Alex on the API spec billable: type: boolean example: true description: >- Whether this entry is billable. Initial value comes from the category default or the workspace default. rate_snapshot_cents: type: integer description: >- Rate snapshot, in cents per hour, captured when this entry was created. example: 12500 deleted_at: $ref: '#/components/schemas/STimePtr' locked_at: $ref: '#/components/schemas/STimePtr' time_created: $ref: '#/components/schemas/STime' time_updated: $ref: '#/components/schemas/STime' TimeEntryAggregateBucket: type: object description: >- A single aggregated bucket. The populated key fields depend on the `group_by` argument. properties: user_id: type: string example: uR2dws11 x-omitempty: true scope_type: $ref: '#/components/schemas/TimeEntryScopeType' scope_id: type: string example: '2700' x-omitempty: true week_start: $ref: '#/components/schemas/STimePtr' billable: type: boolean x-omitempty: true total_seconds: type: integer format: int64 example: 14400 total_cents: type: integer format: int64 description: >- Sum of `duration_seconds * rate_snapshot_cents / 3600` across this bucket. example: 50000 entry_count: type: integer example: 12 SuperthreadErrorCode: type: string description: | Superthread Error Code (`SEC`): A structured error code. Format: `SEC:{ServiceID}-{InternalErrorCode}`. - `SEC`: Prefix for all structured error codes. - `ServiceID`: First 3 characters identify the service, '000' is reserved for generic errors. - `InternalErrorCode`: the next (last) 5 characters define the specific error. pattern: ^SEC:\d{3}-\d{5}$ example: SEC:000-00014 STime: type: integer format: int64 example: 1608742037016 description: unix timestamp in seconds x-go-type: type: STime import: package: github.com/superthread-com/common/pkg/types hints: noValidation: true kind: primitive TimeEntryScopeType: type: string description: > Scope a time entry attaches to. `card` ties the entry to a specific card (and rolls up to its epic), while `category` ties the entry to a workspace-level time category not associated with any card. enum: - card - category example: card STimePtr: type: integer format: int64 example: 1608742037016 description: unix timestamp in seconds x-go-type: type: STime import: package: github.com/superthread-com/common/pkg/types hints: noValidation: true kind: primitive nullable: true securitySchemes: BearerAuth: type: http scheme: bearer ````