> ## 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. # Query time reports > Runs the canonical time-tracking query used by reports. Values within one filter dimension are ORed; different dimensions are ANDed. `direct` roll-up includes only directly selected cards. `descendants` uses the ancestor path captured when each entry was logged and deduplicates cards and entries before totals. Time estimates are owned by time-tracking. Remaining time is derived per card as `max(estimate_seconds - tracked_seconds, 0)` and roll-up remaining is the sum of those direct per-card values. JSON breakdowns contain only groups with tracked time; estimate-only cards remain represented in the authoritative top-level totals. ## OpenAPI ````yaml GET /{team_id}/time/reports 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: Customers description: >- [Service: Customers] Manages customers, customer tiers and statuses, customer settings, and customer requests on cards and projects. Requires the `customers` team feature; not available to workspace guests. - 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: Resourcing description: >- [Service: TimeTracking] Plans people's capacity: working patterns, time off, closures, public holidays, allocations of hours to projects, and retainer budgets. Not available to workspace guests. - 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. - name: PublishedAgents description: >- [Feature] [Service: AI] External API for agents published to websites, apps and custom clients. Authenticated with scoped chat sessions (PublishedAgentSession) or host app assertions (AgentAppAssertion), never with workspace member credentials. Management routes for publications and app registrations live under the Agents tag. Base URL: these paths are absolute from the API origin. The real URL is `https://api.superthread.com/public/agents/v1/...`, and the spec's `basePath` `/v1` does not apply, the same as `/public/forms` (Swagger 2.0 has no per-path base). Generated clients default to `.../v1` and would call `/v1/public/agents/v1/...`, so construct them with the API origin as the base: in TypeScript `new Api({ baseURL: 'https://api.superthread.com' })`, and in Go a transport whose base path is `/`. The www forms portal does the same, using an axios client whose `baseURL` is the API origin. paths: /{team_id}/time/reports: parameters: - $ref: '#/components/parameters/path_team_id' - $ref: '#/components/parameters/query_time_report_from' - $ref: '#/components/parameters/query_time_report_to' - $ref: '#/components/parameters/query_time_timezone' - $ref: '#/components/parameters/query_time_logger_ids' - $ref: '#/components/parameters/query_time_assignee_ids' - $ref: '#/components/parameters/query_time_space_ids' - $ref: '#/components/parameters/query_time_project_ids' - $ref: '#/components/parameters/query_time_board_ids' - $ref: '#/components/parameters/query_time_sprint_ids' - $ref: '#/components/parameters/query_time_card_ids' - $ref: '#/components/parameters/query_time_category_ids' - $ref: '#/components/parameters/query_time_tag_ids' - $ref: '#/components/parameters/query_time_tag_match' - $ref: '#/components/parameters/query_time_report_billable' - $ref: '#/components/parameters/query_time_sources' - $ref: '#/components/parameters/query_time_rollup_mode' - $ref: '#/components/parameters/query_time_group_by' - $ref: '#/components/parameters/query_time_cursor' - $ref: '#/components/parameters/query_time_limit' get: tags: - TimeTracking summary: Query time reports description: > Runs the canonical time-tracking query used by reports. Values within one filter dimension are ORed; different dimensions are ANDed. `direct` roll-up includes only directly selected cards. `descendants` uses the ancestor path captured when each entry was logged and deduplicates cards and entries before totals. Time estimates are owned by time-tracking. Remaining time is derived per card as `max(estimate_seconds - tracked_seconds, 0)` and roll-up remaining is the sum of those direct per-card values. JSON breakdowns contain only groups with tracked time; estimate-only cards remain represented in the authoritative top-level totals. operationId: getTimeReport responses: '200': description: Paginated report buckets and authoritative totals. content: application/json: schema: $ref: '#/components/schemas/GetTimeReportQueryResponse' 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 query_time_report_from: in: query name: from description: >- Lower bound (inclusive) for the report window, as a Unix timestamp in seconds. required: true schema: type: integer format: int64 query_time_report_to: in: query name: to description: >- Upper bound (exclusive) for the report window, as a Unix timestamp in seconds. required: true schema: type: integer format: int64 query_time_timezone: in: query name: timezone description: IANA timezone used for day, week, and month boundaries. required: false schema: type: string query_time_logger_ids: in: query name: logger_ids description: Restrict to entries logged by these member IDs. required: false style: form explode: false schema: type: array items: type: string query_time_assignee_ids: in: query name: assignee_ids description: Restrict to cards currently assigned to any of these member IDs. required: false style: form explode: false schema: type: array items: type: string query_time_space_ids: in: query name: space_ids description: >- Restrict to entries whose card was in these spaces when the time was logged. required: false style: form explode: false schema: type: array items: type: string query_time_project_ids: in: query name: project_ids description: >- Restrict to entries on cards currently in these projects, including time logged before the cards joined. required: false style: form explode: false schema: type: array items: type: string query_time_board_ids: in: query name: board_ids description: >- Restrict to entries whose card was in these boards when the time was logged. required: false style: form explode: false schema: type: array items: type: string query_time_sprint_ids: in: query name: sprint_ids description: >- Restrict to entries whose card was in these sprints when the time was logged. required: false style: form explode: false schema: type: array items: type: string query_time_card_ids: in: query name: card_ids description: >- Restrict to these cards. Descendant roll-up uses the ancestor path captured when each entry was logged. required: false style: form explode: false schema: type: array items: type: string query_time_category_ids: in: query name: category_ids description: Restrict to entries assigned to these time categories. required: false style: form explode: false schema: type: array items: type: string query_time_tag_ids: in: query name: tag_ids description: Restrict to cards currently carrying the selected tags. required: false style: form explode: false schema: type: array items: type: string query_time_tag_match: in: query name: tag_match description: Match cards carrying any selected tag or every selected tag. required: false schema: type: string enum: - any - all query_time_report_billable: in: query name: billable description: >- Optional filter — restrict to billable (`true`) or non-billable (`false`) entries. required: false schema: type: boolean query_time_sources: in: query name: sources description: >- Restrict to entries created manually, by a timer, or by idle-time handling. required: false style: form explode: false schema: type: array items: type: string enum: - manual - timer - idle query_time_rollup_mode: in: query name: rollup_mode description: >- Direct includes only cards in the selected scope; descendants recursively includes every child card. required: false schema: type: string enum: - direct - descendants query_time_group_by: in: query name: group_by description: Independent report grouping dimension. required: false schema: type: string enum: - member - day - week - month - space - project - board - sprint - card - category - tag - billable query_time_cursor: in: query name: cursor description: Opaque cursor for date-bounded time-entry or report pagination. required: false schema: type: string query_time_limit: in: query name: limit description: Page size. The service applies a bounded default and maximum. required: false schema: type: integer minimum: 1 maximum: 500 schemas: GetTimeReportQueryResponse: type: object allOf: - $ref: '#/components/schemas/ResponseMetadata' properties: filters: $ref: '#/components/schemas/TimeQueryFilters' group_by: $ref: '#/components/schemas/TimeReportGroupBy' totals: $ref: '#/components/schemas/TimeTotals' buckets: type: array items: $ref: '#/components/schemas/TimeReportBucket' 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 TimeQueryFilters: type: object description: Exact effective filters applied by entries, reports, and CSV. properties: from: type: integer format: int64 to: type: integer format: int64 timezone: type: string example: Europe/London logger_ids: type: array items: type: string assignee_ids: type: array description: Matches the card's current assignees, not its historical assignees. items: type: string space_ids: type: array description: Matches the space captured on each entry when the work was logged. items: type: string project_ids: type: array description: >- Matches the card's current project, including time logged before it joined. Grouping and export attribution still use historical snapshots. items: type: string board_ids: type: array description: Matches the board captured on each entry when the work was logged. items: type: string sprint_ids: type: array description: Matches the sprint captured on each entry when the work was logged. items: type: string card_ids: type: array items: type: string category_ids: type: array items: type: string tag_ids: type: array description: Matches the card's current tags, not its historical tags. items: type: string tag_match: type: string enum: - any - all billable: type: boolean x-omitempty: true nullable: true sources: type: array items: $ref: '#/components/schemas/TimeEntrySource' rollup_mode: $ref: '#/components/schemas/TimeRollupMode' TimeReportGroupBy: type: string description: Independent grouping dimension for a time report. enum: - member - day - week - month - space - project - board - sprint - card - category - tag - billable example: member TimeTotals: type: object description: Authoritative totals for a set of deduplicated cards and entries. required: - estimate_seconds - tracked_seconds - remaining_seconds - card_count - unestimated_card_count - entry_count properties: estimate_seconds: type: integer format: int64 example: 28800 tracked_seconds: type: integer format: int64 example: 14400 remaining_seconds: type: integer format: int64 description: >- Sum of max(card estimate minus direct tracked duration, zero) for every included card. example: 14400 card_count: type: integer example: 4 unestimated_card_count: type: integer description: Included cards with tracked duration but no time estimate. example: 1 entry_count: type: integer example: 12 money_totals: type: array description: >- Financial totals partitioned by snapshotted currency; currencies are never combined. items: $ref: '#/components/schemas/TimeMoneyTotal' TimeReportBucket: type: object required: - key - totals properties: key: type: string description: Stable ID or period key for the selected grouping. example: uR2dws11 label: type: string example: Alex totals: $ref: '#/components/schemas/TimeTotals' card_ids: type: array description: >- Deduplicated cards represented by this bucket, used for task breakdowns. items: type: string 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 TimeEntrySource: type: string description: How the time entry was created. enum: - manual - timer - idle example: manual TimeRollupMode: type: string description: >- Whether a selected scope includes only its direct cards or every recursive descendant card. enum: - direct - descendants example: direct TimeMoneyTotal: type: object required: - currency - total_cents properties: currency: type: string pattern: ^[A-Z]{3}$ example: GBP total_cents: type: integer format: int64 example: 50000 securitySchemes: BearerAuth: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.