Period comparison report
Compares the chosen period with the periods before it across the main figures, such as this week against earlier weeks. Set format to csv and section to download one table.
Requires: desk.supervise scope, Supervisor licence, Pro plan.
Authorization
bearerAuth A SautiDesk API key. An owner or admin makes it under Settings in SautiDesk for a named person and picks the scopes. The key is shown once. Send it as Authorization: Bearer <key>. It acts as that person and as nobody else.
In: header
Query Parameters
Start of the range: a date (2026-09-01) or a time (RFC 3339). A bare date is that day in the workspace's time zone.
End of the range: a date or a time (RFC 3339). A bare date includes that whole day. The range can be at most 366 days long.
csv to download the report as a CSV file instead of JSON.
On a report that has several tables: with format=csv, the table to download; otherwise, the table that the page parameter turns. Give its number counting from 0, or its title. A CSV without it is the table with the most rows.
The page of the table named by section, counting from 1. A table sends at most 200 rows a page and says how many pages it has; a page past the last is the last. The other tables stay on their first page. A CSV is never paged.
Response
OK
Example
{ "report": "service", "range": { "from": "2026-10-14T08:30:00Z", "to": "2026-10-14T08:30:00Z", "timezone": "Africa/Nairobi" }, "generated_at": "2026-10-14T08:30:00Z", "kpis": [ { "label": "Amina Wanjiru", "value": {}, "type": "billing", "note": "Hi Amina, your order has shipped.", "tone": "example", "better": "example", "delta": 1, "delta_type": "example", "def": "example", "split": [ { "label": null, "value": null, "type": null, "tone": null } ] } ], "sections": [ { "title": "Order 1182 has not arrived", "hint": "example", "count": "example", "cols": [ { "key": null, "label": null, "type": null, "right": null, "w": null } ], "rows": [ [ {} ] ], "total": 3, "page": 1, "page_size": 25, "pages": 1, "alert": [ 1 ], "summary": [ {} ] } ], "notes": [ "Hi Amina, your order has shipped." ], "insight": { "headline": "example", "body": "Hi Amina, your order has shipped.", "icon": "example" }, "charts": [ {} ], "compare": { "label": "Amina Wanjiru", "from": "2026-10-14T08:30:00Z", "to": "2026-10-14T08:30:00Z", "own": false }}reportrequiredstringThe report to send, for example service or calls.rangerequiredobjectfromrequiredstring (date-time)The number or address to send from. It must belong to your workspace.torequiredstring (date-time)Who to send to: a phone number in international format or, for email, an address.timezonerequiredstringgenerated_atrequiredstring (date-time)kpisrequiredobject[]labelrequiredstringA short name to recognise it by.valuerequiredanytyperequiredstringnoterequiredstringA note.tonerequiredstringbetterstringWhich way is good for this figure: up or down. Left out when neither is, for example calls offered.deltanumber | nullThis period's figure minus the previous period's, in the unit of delta_type. Left out when there is nothing to compare.delta_typestringHow delta is written: the figure's own type, except that a percentage moves in points.defstringOne sentence that says what the figure means, for a hover under its label. Left out when there is nothing to add.splitobject[]The parts a headline figure is made of, for example conversations by channel, as segments with a label, value, type and tone. Left out when it has none.labelrequiredstringA short name to recognise it by.valuerequirednumbertyperequiredstringtonestringsectionsrequiredobject[]titlerequiredstringA short title.hintrequiredstringcountstringWhat the table says about its own size, in its own words, for example 4 channels or 42 contacts. Left out when it is the number of rows.colsrequiredobject[]keyrequiredstringlabelrequiredstringA short name to recognise it by.typerequiredstringrightrequiredbooleanwnumberHow much of the table's width the column takes, as a weight: 1 is a plain column and 2 is twice as wide. Left out to size the column by its type.rowsrequiredany[][]totalintegerpageintegerWhich page of the table these rows are, counting from 1. Only on a table with more than one page. Ask for another with the page and section request parameters.page_sizeintegerThe most rows a page of this table has (200). Only on a table with more than one page.pagesintegerHow many pages there are to ask for. Only on a table with more than one page.alertrequiredinteger[]summaryany[]A total row for a table that has one, with one cell per column as a row's cells are. Left out when the table has none.notesrequiredstring[]Notes about the call or the ticket.insightanyA short written reading of the report, built from its own numbers. Left out when there is nothing to say.headlinerequiredstringThe one-line finding.bodyrequiredstringA sentence or two that explain the finding.iconrequiredstringThe name of the icon to show beside it.chartsany[]Charts to draw for the report, in order. Each has a kind (for example hbars, columns, scatter, stack, band, heat or timeline), a title and its data. Ignore a kind you do not know. Left out when there is nothing to draw.compareanyWhat the changes in this report are measured against, for example the same weekday a week earlier. Left out when compare is off or there is nothing to compare with.labelrequiredstringWhat the comparison is against, for example vs last Thursday.fromstring (date-time) | nullStart of the comparison period. Left out when the report uses its own baseline.tostring (date-time) | nullEnd of the comparison period. Left out when the report uses its own baseline.ownbooleanTrue when the report measures against its own baseline, such as the usual week or the forecast, so no second period was run.curl -X GET "https://api.sautidesk.com/v1/desk/reports/week?from=string&to=string"