Report Chart
A team-scoped saved reporting chart that aggregates task data (live, events, or historical) across one or more projects. Carries a chart type, a task filter, and a set of data series.
List Report Charts
List reportCharts. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 4 fields. Ordered by createdAt unless you pass sort.
Required scope: report-charts:read
query Parameters
sortField to sort by. Prefix with - for descending (-createdAt); a createdAt:desc / createdAt:asc suffix works too, but never both markers at once. Default: createdAt.
cursorOpaque cursor for the next page (the envelope nextCursor).
limitItems per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow nextCursor instead of assuming one page held everything.
includeTotalWhen true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination.
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
name[eq]Filter where name equals.
name[contains]Filter where name contains.
name[startsWith]Filter where name starts with.
dataType[eq]Filter where dataType equals.
chartType[eq]Filter where chartType equals.
createdAt[gt]Filter where createdAt is greater than.
createdAt[gte]Filter where createdAt is greater than or equal to.
createdAt[lt]Filter where createdAt is less than.
createdAt[lte]Filter where createdAt is less than or equal to.
List Report Charts › Responses
OK
The page of results.
totalTotal rows matching the query (across pages).
limithasMorenextCursorOpaque cursor for the next page; null on the last page.
Create Report Chart
Create a Report Chart. Server-assigned fields are ignored if sent.
Required scope: report-charts:write
query Parameters
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Create Report Chart › Request Body
projectsThe projects whose tasks this chart aggregates. At least one is required. On update, use POST/DELETE /report-charts/{id}/projects.
dataTypeAggregation mode for the chart: live, events, or historical.
chartTypeVisualization type: line, bar, area, areaStacked, pie, table, number, or funnel.
Restricts the chart to a window of time. Omitted is stored (and read back) as {} rather than null.
Which tasks the chart counts. Every facet is optional; omit the whole object for no filter, and note that an omitted filter is stored (and read back) as {} rather than null.
The lines, bars or slices the chart draws, in order. Omit it and the chart is created with none (stored and read back as []); send it and it must have at least one entry.
nameOptional display name for the chart.
Create Report Chart › Responses
Created
idUnique identifier for this resource.
createdAtCreation timestamp.
dataTypeAggregation mode for the chart: live, events, or historical.
chartTypeVisualization type: line, bar, area, areaStacked, pie, table, number, or funnel.
updatedAtLast update timestamp.
createdByActorIdWho created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
updatedByActorIdWho last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
createdByActorTypeThe creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type; read-only, not directly writable.
updatedByActorTypeThe last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type via the row's updatedByActorId; read-only, not directly writable.
Restricts the chart to a window of time. Omitted is stored (and read back) as {} rather than null.
Which tasks the chart counts. Every facet is optional; omit the whole object for no filter, and note that an omitted filter is stored (and read back) as {} rather than null.
The lines, bars or slices the chart draws, in order. Omit it and the chart is created with none (stored and read back as []); send it and it must have at least one entry.
nameOptional display name for the chart.
projectsThe projects whose tasks this chart aggregates. At least one is required when the chart is created. Read them back with ?expand=projects, or edit them one at a time via POST/DELETE /report-charts/{id}/projects.
The related Actor, present only when you pass ?expand=createdByActor.
The related Actor, present only when you pass ?expand=updatedByActor.
Get Report Chart
Retrieve a single Report Chart by id.
Required scope: report-charts:read
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Report Chart.
query Parameters
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
Get Report Chart › Responses
OK
idUnique identifier for this resource.
createdAtCreation timestamp.
dataTypeAggregation mode for the chart: live, events, or historical.
chartTypeVisualization type: line, bar, area, areaStacked, pie, table, number, or funnel.
updatedAtLast update timestamp.
createdByActorIdWho created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
updatedByActorIdWho last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
createdByActorTypeThe creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type; read-only, not directly writable.
updatedByActorTypeThe last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type via the row's updatedByActorId; read-only, not directly writable.
Restricts the chart to a window of time. Omitted is stored (and read back) as {} rather than null.
Which tasks the chart counts. Every facet is optional; omit the whole object for no filter, and note that an omitted filter is stored (and read back) as {} rather than null.
The lines, bars or slices the chart draws, in order. Omit it and the chart is created with none (stored and read back as []); send it and it must have at least one entry.
nameOptional display name for the chart.
projectsThe projects whose tasks this chart aggregates. At least one is required when the chart is created. Read them back with ?expand=projects, or edit them one at a time via POST/DELETE /report-charts/{id}/projects.
The related Actor, present only when you pass ?expand=createdByActor.
The related Actor, present only when you pass ?expand=updatedByActor.
Delete Report Chart
Permanently delete this Report Chart. This cannot be undone.
Required scope: report-charts:delete
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Report Chart.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Delete Report Chart › Responses
No Content
Update Report Chart
Partially update a Report Chart. Only the fields you send are changed.
Required scope: report-charts:write
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Report Chart.
query Parameters
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Update Report Chart › Request Body
projectsThe projects whose tasks this chart aggregates. At least one is required. On update, use POST/DELETE /report-charts/{id}/projects.
dataTypeAggregation mode for the chart: live, events, or historical.
chartTypeVisualization type: line, bar, area, areaStacked, pie, table, number, or funnel.
Restricts the chart to a window of time. Omitted is stored (and read back) as {} rather than null.
Which tasks the chart counts. Every facet is optional; omit the whole object for no filter, and note that an omitted filter is stored (and read back) as {} rather than null.
The lines, bars or slices the chart draws, in order. Omit it and the chart is created with none (stored and read back as []); send it and it must have at least one entry.
nameOptional display name for the chart.
expectedUpdatedAtOptional concurrency guard: the updatedAt you last read. If the resource has changed since, the update is rejected with 409 instead of overwriting the other writer. Re-read, re-derive your change from the current values, and retry with the fresh updatedAt.
Update Report Chart › Responses
OK
idUnique identifier for this resource.
createdAtCreation timestamp.
dataTypeAggregation mode for the chart: live, events, or historical.
chartTypeVisualization type: line, bar, area, areaStacked, pie, table, number, or funnel.
updatedAtLast update timestamp.
createdByActorIdWho created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
updatedByActorIdWho last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
createdByActorTypeThe creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type; read-only, not directly writable.
updatedByActorTypeThe last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type via the row's updatedByActorId; read-only, not directly writable.
Restricts the chart to a window of time. Omitted is stored (and read back) as {} rather than null.
Which tasks the chart counts. Every facet is optional; omit the whole object for no filter, and note that an omitted filter is stored (and read back) as {} rather than null.
The lines, bars or slices the chart draws, in order. Omit it and the chart is created with none (stored and read back as []); send it and it must have at least one entry.
nameOptional display name for the chart.
projectsThe projects whose tasks this chart aggregates. At least one is required when the chart is created. Read them back with ?expand=projects, or edit them one at a time via POST/DELETE /report-charts/{id}/projects.
The related Actor, present only when you pass ?expand=createdByActor.
The related Actor, present only when you pass ?expand=updatedByActor.
Add projects to a Report Chart
Link the given ids to this Report Chart as projects. Adds to the existing set rather than replacing it, and adding one that is already linked changes nothing. Returns the complete projects set afterwards.
Required scopes: report-charts:write report-charts:link
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Report Chart.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Add projects to a Report Chart › Request Body
idsProjects to add or remove, by id.
Add projects to a Report Chart › Responses
OK
The complete projects set after the change.
affectedIdsThe ids that were actually linked (ones already linked are omitted).
missingIdsIds you sent that do not exist or are not visible to this token.
Remove projects from a Report Chart
Unlink the given ids from this Report Chart's projects. Removing one that is not linked changes nothing. Returns the complete projects set afterwards.
Required scopes: report-charts:write report-charts:link
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Report Chart.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Remove projects from a Report Chart › Request Body
idsProjects to add or remove, by id.
Remove projects from a Report Chart › Responses
OK
The complete projects set after the change.
affectedIdsThe ids that were actually unlinked (ones not linked are omitted).