> For the complete documentation index, see [llms.txt](https://docs.cubicl.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cubicl.io/api-integration/reports.md).

# Reports

Project timer records and time spent in task stages. Viewing reports in the project is required.

## Get timer report

> Returns finished timer records in the project and date range. Report permission is required.

```json
{"openapi":"3.0.3","info":{"title":"Cubicl API","version":"1.0.0"},"tags":[{"name":"Reports","description":"Project timer records and time spent in task stages. Viewing reports in the project is required."}],"servers":[{"url":"https://cubicl.io/api/v1","description":"Cubicl production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Access token from the Integrations page. Header: `Authorization: Bearer YOUR_ACCESS_TOKEN`."}},"schemas":{"ObjectId":{"type":"string","description":"MongoDB ObjectId"},"UnixTimestamp":{"type":"number","description":"Unix timestamp (seconds)"},"TimerList":{"type":"array","items":{"$ref":"#/components/schemas/Timer"}},"Timer":{"type":"object","properties":{"_id":{"type":"string"},"task":{"$ref":"#/components/schemas/TimeReportTask"},"user":{"type":"string"},"group":{"type":"string"},"start":{"type":"number"},"end":{"type":"number"},"createdAt":{"type":"number"},"updatedAt":{"type":"number"}}},"TimeReportTask":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"group":{"type":"string"},"state":{"type":"string"},"priority":{"type":"number"},"assignedBy":{"type":"string"},"assignees":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"parent":{"description":"May be a task object if `fetch=parent`"},"subtasks":{"description":"May be task objects if `fetch=subtasks`"},"steps":{"type":"array","items":{"type":"object"}},"stepType":{"type":"string"},"completedAt":{"type":"number"},"private":{"type":"boolean"},"estimatedTime":{"type":"number"},"trackingNumber":{"type":"string"},"breadcrumbs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"group":{"type":"string"}}}}}},"ErrorCodeMessage":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer","description":"Application error code. Not an HTTP status code."},"message":{"type":"string"}}},"ValidationError":{"type":"object","properties":{"message":{"type":"string"},"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}},"responses":{"Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorCodeMessage"}}}},"NotFound":{"description":"Not found"},"ValidationFailed":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}}},"paths":{"/reports/timers":{"get":{"tags":["Reports"],"summary":"Get timer report","description":"Returns finished timer records in the project and date range. Report permission is required.","operationId":"getTimerReport","parameters":[{"name":"group","in":"query","required":true,"schema":{"$ref":"#/components/schemas/ObjectId"},"description":"Project ID"},{"name":"from","in":"query","required":true,"schema":{"$ref":"#/components/schemas/UnixTimestamp"},"description":"Start (Unix seconds)"},{"name":"to","in":"query","required":true,"schema":{"$ref":"#/components/schemas/UnixTimestamp"},"description":"End (Unix seconds)"},{"name":"recursive","in":"query","required":true,"schema":{"type":"string","enum":["true","false"]},"description":"`\"true\"`: include subprojects. `\"false\"`: the given project only."},{"name":"archived","in":"query","schema":{"type":"string","enum":["true","false","all"]},"description":"`true`: archived. `false`: not archived. `all`: all."},{"name":"fetch","in":"query","schema":{"type":"string"},"description":"Comma-separated extra data: `parent`, `subtasks`"},{"name":"user","in":"query","schema":{"$ref":"#/components/schemas/ObjectId"},"description":"ID of the user who created the timer. If omitted, all users."},{"name":"skip","in":"query","schema":{"type":"number","minimum":0},"description":"Number of records to skip. Minimum 0. If omitted, no skip."},{"name":"limit","in":"query","schema":{"type":"number","minimum":1},"description":"Number of records to return. Minimum 1. If omitted, no limit."}],"responses":{"200":{"description":"Timer report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimerList"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"}}}}}}
```

## Get task stage times

> Returns time tasks spent in stages in a project.

```json
{"openapi":"3.0.3","info":{"title":"Cubicl API","version":"1.0.0"},"tags":[{"name":"Reports","description":"Project timer records and time spent in task stages. Viewing reports in the project is required."}],"servers":[{"url":"https://cubicl.io/api/v1","description":"Cubicl production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Access token from the Integrations page. Header: `Authorization: Bearer YOUR_ACCESS_TOKEN`."}},"schemas":{"ObjectId":{"type":"string","description":"MongoDB ObjectId"},"UnixTimestamp":{"type":"number","description":"Unix timestamp (seconds)"},"TaskStageTimeList":{"type":"array","items":{"$ref":"#/components/schemas/TaskStageTime"}},"TaskStageTime":{"type":"object","description":"`type=task`: each item is a task. `type=user`: each item is a user; `assignees` and `lastState` are omitted. `stateStats` values are seconds; keys are stage names.","properties":{"_id":{"type":"string"},"name":{"type":"string"},"assignees":{"type":"array","items":{"type":"string"}},"lastState":{"type":"string"},"stateStats":{"type":"object","additionalProperties":{"type":"number"}}}},"ErrorCode":{"type":"object","required":["code"],"properties":{"code":{"type":"integer","description":"Application error code. Not an HTTP status code."}}},"ValidationError":{"type":"object","properties":{"message":{"type":"string"},"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}},"responses":{"ForbiddenCode":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorCode"}}}},"ValidationFailed":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}}},"paths":{"/reports/task-stage-times":{"get":{"tags":["Reports"],"summary":"Get task stage times","operationId":"getTaskStageTimes","parameters":[{"name":"group","in":"query","required":true,"schema":{"$ref":"#/components/schemas/ObjectId"},"description":"Project ID"},{"name":"start","in":"query","required":true,"schema":{"$ref":"#/components/schemas/UnixTimestamp"},"description":"Start (Unix seconds)"},{"name":"end","in":"query","required":true,"schema":{"$ref":"#/components/schemas/UnixTimestamp"},"description":"End (Unix seconds)"},{"name":"type","in":"query","schema":{"type":"string","enum":["user","task"]},"description":"How the report is grouped: `user` or `task`"},{"name":"archived","in":"query","schema":{"type":"string","enum":["true","false","all"]},"description":"`true`: archived. `false`: not archived. `all`: all."}],"responses":{"200":{"description":"Stage time report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskStageTimeList"}}}},"403":{"$ref":"#/components/responses/ForbiddenCode"},"422":{"$ref":"#/components/responses/ValidationFailed"}},"description":"Returns time tasks spent in stages in a project."}}}}
```

## Get task stage times by IDs

> Returns stage times for multiple tasks. Tasks may be in different projects; report permission is required for each project.

```json
{"openapi":"3.0.3","info":{"title":"Cubicl API","version":"1.0.0"},"tags":[{"name":"Reports","description":"Project timer records and time spent in task stages. Viewing reports in the project is required."}],"servers":[{"url":"https://cubicl.io/api/v1","description":"Cubicl production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Access token from the Integrations page. Header: `Authorization: Bearer YOUR_ACCESS_TOKEN`."}},"schemas":{"GetTaskStageTimesByIdsRequest":{"type":"object","required":["taskIds","start","end"],"properties":{"taskIds":{"type":"array","items":{"type":"string"},"description":"Task ID list"},"start":{"type":"number","description":"Start (Unix seconds)"},"end":{"type":"number","description":"End (Unix seconds)"},"type":{"type":"string","enum":["user","task"],"description":"How the report is grouped: `user` or `task`"}}},"TaskStageTimeList":{"type":"array","items":{"$ref":"#/components/schemas/TaskStageTime"}},"TaskStageTime":{"type":"object","description":"`type=task`: each item is a task. `type=user`: each item is a user; `assignees` and `lastState` are omitted. `stateStats` values are seconds; keys are stage names.","properties":{"_id":{"type":"string"},"name":{"type":"string"},"assignees":{"type":"array","items":{"type":"string"}},"lastState":{"type":"string"},"stateStats":{"type":"object","additionalProperties":{"type":"number"}}}},"ErrorCodeMessage":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer","description":"Application error code. Not an HTTP status code."},"message":{"type":"string"}}},"ErrorMessage":{"type":"object","required":["message"],"properties":{"message":{"type":"string"}}},"ValidationError":{"type":"object","properties":{"message":{"type":"string"},"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}},"responses":{"Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorCodeMessage"}}}},"NotFound":{"description":"Not found"}}},"paths":{"/reports/task-stage-times-by-ids":{"post":{"tags":["Reports"],"summary":"Get task stage times by IDs","description":"Returns stage times for multiple tasks. Tasks may be in different projects; report permission is required for each project.","operationId":"getTaskStageTimesByIds","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetTaskStageTimesByIdsRequest"}}}},"responses":{"200":{"description":"Stage time report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskStageTimeList"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Invalid operation","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErrorMessage"},{"$ref":"#/components/schemas/ValidationError"}]}}}}}}}}}
```
