Flow API: reports, SLA and business calendar
Flow reports compute data on the server: how many objects are in each status, the total deal amount per manager, the funnel conversion, how much work is left in a sprint, how long tasks sit in progress, what share of requests is closed on time. This article covers the report methods, dashboards, SLA reports and the workspace's business calendar.
General rules — the base URL, keys, headers and errors — are in Flow API: basics. The "Reports" screen and the "Business hours" settings in the interface are described in Flow: reports, SLA and business calendar.
Methods
Method | Request | What it returns |
|---|---|---|
Aggregates |
| Counts, sums, averages, minimums and maximums with grouping |
Funnel |
| Conversion by process stage for objects created in a period |
Burndown |
| Remaining work for each day and the ideal line |
Dashboards |
| Saved sets of tiles: personal and shared |
Summary across all workspaces |
| Object counters across all of a person's workspaces; session only |
Time in status by type |
| For each status: entries, exits, time spent, how many objects are there now |
SLA summary by type |
| For each SLA: met, breached, still running, share met on time |
SLA breaches |
| List of breaches in a period, paginated |
Object's time in status |
| The object's stays in statuses and totals |
Object's SLA |
| The object's breaches and running deadlines |
Time report |
| Time logged in a period by person, object or parent object |
Time export |
| Time entries for a period as a CSV file |
Business calendar |
| Time zone, working hours, days off |
Replace the calendar |
| The saved calendar |
Paths are relative to https://flow.sensever.com/v1. Reports only read data: POST /reports/* is a way to pass a condition, and Idempotency-Key isn't needed. Dashboard changes accept Idempotency-Key, like other changes.
Permissions and limits
A report sees only objects you can read: the
ownandteamrestrictions of your role apply before the conditions.Grouping and metric fields are checked like filter fields: a field you can't read (or read with a narrower scope than the object itself) returns
403 FIELD_NOT_READABLE. Hidden fields are never summed.Aggregates don't count archived objects unless the condition explicitly mentions
system: archived. Time in status, funnel and burndown are history reports: how each of them counts archived objects is stated for each report.An aggregate reads the entire selection, so the workspace's query plan cost threshold is always checked, and execution time is limited to 3 seconds. Exceeding it returns
422 QUERY_TOO_EXPENSIVEwithdetails.reasonplan_costorstatement_timeout. Narrow the condition or enable an index for the filter fields.Period reports accept a period no longer than 366 days. Funnel and burndown are cost-limited the same way as aggregates.
Aggregates
POST /reports/aggregate. The selection is set in exactly one of two ways: query or view_id.
Field | Type | Required | Description |
|---|---|---|---|
| object | one of the two |
|
| uuid | one of the two | A saved view: its condition is used (requires the |
| object | no | Only together with |
| object | no | Grouping: |
| array | no | 1–10 metrics |
| integer | no | How many groups to return, 1–200, default 50 |
The where condition is written the same way as in POST /objects/query — see Flow API: query language and search.
Grouping
| By what |
|---|---|
| Status |
| Assignee |
| Author |
| Creation date; the same for |
| A field of type |
bucket is day, week (starting Monday) or month, in UTC; for date and datetime fields the default is day. For multi_enum, multi_principal and tags fields, an object falls into the group of each of its values.
Metrics
| Fields |
|---|---|
| No field |
|
|
|
|
Money isn't converted: if the selection has several currencies, the value is null and mixed_currencies: true.
Example
Open deals by status: count and total amount.
curl -s https://flow.sensever.com/v1/reports/aggregate \
-H "Authorization: Bearer $FLOW_KEY" \
-H "X-Workspace-Id: $WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"query": {"type": "deal", "where": {"system": "state.category", "op": "ne", "value": "done"}},
"group_by": {"system": "state"},
"metrics": [{"fn": "count"}, {"fn": "sum", "field": "amount"}],
"limit": 20
}'{
"type": "deal",
"group_by": {"system": "state"},
"groups": [
{
"key": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6c01",
"state": {"id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6c01", "key": "negotiation", "category": "in_progress"},
"count": 12,
"metrics": [
{"fn": "count", "field": null, "value": "12"},
{"fn": "sum", "field": "amount", "value": "1840000.00", "currency": "RUB", "mixed_currencies": false}
]
}
],
"total": {
"count": 12,
"metrics": [
{"fn": "count", "field": null, "value": "12"},
{"fn": "sum", "field": "amount", "value": "1840000.00", "currency": "RUB", "mixed_currencies": false}
]
},
"truncated": false,
"meta": {"unindexed_fields": []}
}groups[].keyis the group value as a string: a status or person id, an option key,true/false, the interval start date;nullmeans objects without a value. Grouping by status also includesstatewith its key and category.Metric values are strings: decimal numbers without loss of precision,
YYYY-MM-DDfor dates, RFC 3339 UTC for timestamps,nullif there are no values.Groups are sorted by
countdescending, then by key.truncated: truemeans there were more groups thanlimit.meta.unindexed_fieldslists fields whose condition ran without an index.When querying by
view_id, the response also includesview_id.
Funnel
POST /reports/funnel shows how many objects reached each stage of the status process. The selection is set the same way as for aggregates: exactly one of query or view_id (+ where).
Field | Type | Required | Description |
|---|---|---|---|
| object / uuid | one of the two | Selection, as in |
| object | no | Only together with |
| string | yes | Period by the object's creation date, |
| array or null | no | Status keys in funnel order, 2–20. Defaults to the statuses of the current process version in order, except the |
| string or null | no | A |
{
"query": {"type": "deal"},
"from": "2026-07-01",
"to": "2026-10-01",
"sum_field": "amount"
}How it is calculated:
Cohort (
cohort) — objects in the selection created in the period.An object has reached a stage (
reached) if it ever entered this stage or any later stage of the funnel: skipping a stage doesn't lose the object.enteredis how many entered this exact stage.conversion_from_previousisreached/reachedof the previous stage,conversion_from_firstis relative to the first stage, from 0 to 1;nullfor the first stage or when there is nothing to divide by.median_seconds_from_previousis the median time between the first entries into the previous stage and this one among objects that entered both;median_pairsis how many objects it was calculated over.outcomesis the cohort by the category of the current status:done,cancelled,open(everything else),done_rate,cancelled_rate.Entries are taken from the transition history and the current status. History is kept for 12 months: older transitions aren't counted, except the current status.
Response:
{
"type": "deal",
"from": "2026-07-01T00:00:00.000000Z",
"to": "2026-10-01T00:00:00.000000Z",
"cohort": 120,
"sum_field": "amount",
"sum_data_type": "money",
"cohort_sums": [{"currency": "EUR", "sum": "84000.00", "count": 20}, {"currency": "RUB", "sum": "9600000.00", "count": 96}],
"stages": [
{
"state": {"id": "…", "key": "new", "category": "open"},
"reached": 120, "entered": 118,
"conversion_from_previous": null, "conversion_from_first": 1,
"median_seconds_from_previous": null, "median_pairs": null,
"sums": [{"currency": "EUR", "sum": "84000.00", "count": 20}, {"currency": "RUB", "sum": "9600000.00", "count": 96}]
},
{
"state": {"id": "…", "key": "qualified", "category": "in_progress"},
"reached": 72, "entered": 65,
"conversion_from_previous": 0.6, "conversion_from_first": 0.6,
"median_seconds_from_previous": 172800, "median_pairs": 65,
"sums": [{"currency": "RUB", "sum": "6100000.00", "count": 70}]
}
],
"outcomes": {
"done": 18, "cancelled": 40, "open": 62, "done_rate": 0.15, "cancelled_rate": 0.3333,
"sums": {
"done": [{"currency": "RUB", "sum": "2100000.00", "count": 18}],
"cancelled": [{"currency": "EUR", "sum": "30000.00", "count": 8}, {"currency": "RUB", "sum": "2900000.00", "count": 30}],
"open": [{"currency": "EUR", "sum": "54000.00", "count": 12}, {"currency": "RUB", "sum": "4600000.00", "count": 48}]
}
}
}Sums. With sum_field, the funnel adds up the field's current value: for objects that reached a stage (stages[].sums), for the cohort (cohort_sums) and for outcomes (outcomes.sums). An item is {currency, sum, count}: sum is a decimal string, count is the number of objects with a value. Money is summed separately per currency, without conversion; items are sorted by currency code. A numeric field has one item with currency: null. Without sum_field, all sums are null. A field you can't read returns 403 FIELD_NOT_READABLE; a field of another data type returns 422 VALIDATION_FAILED on sum_field.
A type without a status process returns 422 VALIDATION_FAILED (no_lifecycle). Cost is limited as for aggregates: 422 QUERY_TOO_EXPENSIVE.
Burndown
POST /reports/burndown returns, for each day of the period, how many objects in the selection are not in a status of the done or cancelled categories at the end of the day, plus the ideal line.
Field | Type | Required | Description |
|---|---|---|---|
| object / uuid | one of the two | Selection, as in |
| object | no | Only together with |
| string | yes |
|
| string or null | no | IANA time zone for day boundaries; defaults to UTC |
| string or null | no | A |
| boolean or null | no | Ideal line by working days; defaults to |
{
"view_id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6d10",
"from": "2026-09-22",
"to": "2026-10-03",
"time_zone": "Europe/Moscow",
"sum_field": "estimate_hours"
}The response contains type, from, to, time_zone, sum_field, working_days, calendar, start and days[]:
Field | Description |
|---|---|
| Values at the start of the period (midnight of |
| The day and the moment of the values: end of day; for today, now; for future days, |
| Objects in the selection that are neither done nor cancelled at that moment; |
| The sum of |
| Scope: objects in the selection created and not archived by that moment |
| The ideal line from |
| Whether it is a working day; |
|
|
The selection is computed from current data: a task just moved to another sprint drops out of the previous sprint's report for all days. Archived objects are counted up to the moment of archiving.
Past statuses are reconstructed from the transition history.
working_days: true(default): the ideal line descends only on working days of the workspace calendar (GET /workspace/calendar: a weekday with working intervals that isn't a holiday) and stays flat on non-working days. Without a saved calendar, Monday–Friday applies (calendar.is_default: true). If the period has no working days, the line descends by calendar days.false— the line descends every day. Actual values don't depend on the calendar.A sum field you can't read returns
403 FIELD_NOT_READABLE; a non-numeric one returns422 VALIDATION_FAILEDonsum_field. Cost is limited as for the funnel.
Dashboards
A dashboard is a saved set of report tiles that the interface shows on the "Dashboard" tab. Tiles only describe reports: the data is computed each time by the /reports/* methods with the permissions of the viewer.
Method | Request | Permissions |
|---|---|---|
List |
|
|
Create |
| personal — |
Read with tiles |
|
|
Update |
| personal — author; shared, as well as changing visibility — |
Delete |
| same as update |
Permissions are checked with view rows without an object type. The own scope of view.manage allows changing only your own shared dashboards; all allows any. Someone else's personal dashboard returns 404 NOT_FOUND.
Dashboard: id, name (1–200 characters), visibility (private — visible only to the author, shared — to everyone with view.read), position (order in the list), tile_count, created_by, version, can_manage (whether the caller can change the dashboard and its visibility), created_at, updated_at, tiles. The list returns dashboards without tiles: shared ones and your own personal ones, by position, then by name.
POST /dashboards:
{
"name": "Sales: week",
"visibility": "shared",
"tiles": [
{"id": "t1", "kind": "aggregate", "title": "Deals by status", "type": "deal", "view_id": null, "period": "90",
"group": {"system": "state"}, "metric": {"fn": "sum", "field": "amount"}},
{"id": "t2", "kind": "funnel", "title": "Funnel", "type": "deal", "view_id": null, "period": "90", "sum_field": "amount"},
{"id": "t3", "kind": "burndown", "title": "Sprint", "type": "task", "view_id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6d10",
"period": "all", "from": "2026-09-22", "to": "2026-10-03", "sum_field": null}
]
}Tile field | Description |
|---|---|
| 1–64 characters |
|
|
| 1–200 characters |
| Object type key |
| A filter view or |
|
|
|
|
|
|
|
|
|
|
Other tile keys are stored as is if the name matches [a-z][a-z0-9_]{0,39}, the value is null, a boolean, a number or a string up to 200 characters, and there are no more than 8 such keys. This lets the client store its own simple tile settings.
Limits: no more than 50 tiles and 48 KB of tiles per dashboard, 50 dashboards per author, 100 shared dashboards per workspace. Tile errors return 422 VALIDATION_FAILED with paths like tiles[2].group; exceeding the number of dashboards returns 422 LIMIT_EXCEEDED (details.reason: dashboards_per_owner or shared_dashboards).
PATCH /dashboards/{id} changes the fields you pass (name, visibility, position, tiles — tiles are replaced entirely) and requires expected_version — the dashboard's current version. If the dashboard has been changed in the meantime, the response is 409 OBJECT_VERSION_CONFLICT with details.expected_version and details.actual_version: re-read the dashboard and retry. A request with no changes returns the dashboard as is and doesn't increment version. A shared dashboard that loses shared becomes the author's personal dashboard.
DELETE /dashboards/{id} returns {"id": "…", "deleted": true}; a repeat returns 404. The change history of dashboards remains in the audit log.
Summary across all workspaces
POST /me/reports/summary is the report of "All workspaces" mode: counters of objects the person can read, across all workspaces where they are an active member. Browser session or embed token only; an API key gets 401, and X-Workspace-Id isn't needed.
Body field | Description |
|---|---|
| Only these workspaces, up to 100 |
|
|
| How many recent weeks (including the current one) to return in |
| How many assignees to return in |
Response:
Field | Description |
|---|---|
| Today's date in UTC — overdue status is calculated from it |
|
|
| The same counters per workspace, with |
| Assignees with the most objects: |
| Objects without an assignee and those of the remaining assignees: |
|
|
|
|
An overdue object is one whose due date in its type's due_date or due_at field is earlier than as_of, and whose status isn't in the done or cancelled categories. A type whose due date field you can't read isn't counted as overdue. Assignees are merged by Flow user; another person's user_id and name are returned only if you have workspace.read in that workspace; otherwise their objects are counted in owners.others. Archived objects aren't counted.
Time report
POST /reports/time totals the time logged on objects (time tracking, timer) for a period [from, to) no longer than 366 days: by person (group_by: "person", default), by object (object) or by the relation's parent object (relation, for example by task projects). Filters are billable, type, principal_id. Only entries on objects you can read are counted. There are no more than 1000 groups (truncated); totals are calculated over all of them.
{"from": "2026-09-01T00:00:00+03:00", "to": "2026-10-01T00:00:00+03:00", "group_by": "relation", "relation": "task_project"}GET /reports/time/export with the same filters in the query string (and tz for dates in the file) returns the entries as a CSV file — up to 50,000 rows. Request and response fields, permissions and errors are described in "Flow API: time tracking".
Time in status
By type
POST /reports/time-in-state:
Field | Type | Required | Description |
|---|---|---|---|
| string | yes | Type key or id |
| string | yes | Period start: a |
| string | yes | Period end (exclusive) in the same format |
{"type": "task", "from": "2026-09-01", "to": "2026-10-01"}The response is {type, from, to, states: […]}. For each status (first the statuses of the current process version in order, then statuses of earlier versions):
Field | Description |
|---|---|
|
|
| Entries into the status during |
| How many of them have already left the status (exits after |
| How many are still in the status |
| Duration of completed stays: |
| How many objects are in the status now ( |
Moving objects when a new process version is published, which leaves an object in the same status, counts as neither an entry nor an exit. Archived objects are counted in history but not in current. The object.read permission on the type is required. Duration is calendar time.
By object
GET /reports/objects/{id}/time-in-state returns the object's stays in statuses from the transition history, oldest to newest, and totals:
state— the current status;stays[]—state,entered_at,left_at(nullfor the current stay, which lasts until now),duration_seconds;totals[]—state,visits,duration_seconds;history_complete: false— the beginning of the history has already been deleted (it is kept for at least 12 months) or the object has more than 1000 transitions.
An object you can't read returns 404 OBJECT_NOT_FOUND.
SLA
An SLA is set in a type's status process: how long an object may stay in a status. The format in the process graph is "sla": [{"key", "state", "duration", "business_hours"}]; learn more in Flow API: types, fields, statuses and publishing. When the deadline passes, a breach is recorded and the sla.breached event is published. One entry into a status produces no more than one breach of each SLA.
Summary by type
POST /reports/sla with the same body as time in status (type, from, to). For each SLA of the published process versions:
Field | Description |
|---|---|
| The SLA and its status |
| ISO 8601 duration (business time if |
| Whether it is counted in business time |
| Entries into the status during the period on versions with this SLA |
| Left without a breach |
| Breached |
| Still in the status and not breached |
| Share met on time: |
duration and business_hours are taken from the newest version with this SLA.
Breaches
POST /reports/sla/breaches:
Field | Type | Required | Description |
|---|---|---|---|
| string | yes | Object type |
| string | yes | Period by breach time |
| string or null | no | Only this SLA |
| object | no |
|
The response is {items, page: {size, next_cursor}}; items are sorted by breached_at, object and key:
{
"items": [
{
"object_id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b72",
"title": "Verification code email not arriving",
"sla_key": "first_response",
"state": {"id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6c02", "key": "new", "category": "open"},
"state_entered_at": "2026-09-22T08:10:00.000000Z",
"deadline": "2026-09-22T12:10:00.000000Z",
"breached_at": "2026-09-22T12:10:03.000000Z",
"left_at": "2026-09-22T13:02:41.000000Z"
}
],
"page": {"size": 50, "next_cursor": null}
}left_at is when the object left the status (null means it is still there). For the next page, send the same request with page.cursor = next_cursor. A cursor from another report returns 422 VALIDATION_FAILED on page.cursor.
Object's SLA
GET /reports/objects/{id}/sla returns {object_id, breaches, running}:
breaches[]— the object's breaches:sla_key,state_id,state_entered_at,lifecycle_version_id,deadline,breached_at,event_id;running[]— SLAs currently running in the current status:sla_key,state_id,state_entered_at,deadline,business_hours.
Business calendar
The workspace calendar defines business time for SLAs with business_hours: true: the time zone, working intervals by weekday and non-working dates.
Read
GET /workspace/calendar (workspace.read permission):
{
"timezone": "Europe/Moscow",
"week": {
"mon": [{"from": "09:00", "to": "13:00"}, {"from": "14:00", "to": "18:00"}],
"tue": [{"from": "09:00", "to": "18:00"}],
"wed": [{"from": "09:00", "to": "18:00"}],
"thu": [{"from": "09:00", "to": "18:00"}],
"fri": [{"from": "09:00", "to": "17:00"}],
"sat": [],
"sun": []
},
"holidays": ["2026-11-04", "2026-12-31"],
"is_default": false,
"version": 3,
"updated_at": "2026-09-24T19:40:00.000000Z"
}A workspace without its own calendar gets the default calendar: Monday–Friday 09:00–18:00 UTC, is_default: true, version: 0.
Replace
PUT /workspace/calendar (workspace.manage permission) replaces the calendar entirely:
Field | Type | Required | Description |
|---|---|---|---|
| string | yes | IANA time zone, for example |
| object | yes | Days |
| array | no | Up to 500 non-working dates |
The week must have at least one working interval. Errors come with paths like week.mon[0].from and the codes invalid_time, empty_interval, overlapping_intervals, no_working_time, invalid_timezone, invalid_date.
A changed calendar gets version + 1 and an audit entry. Saving the same calendar again changes nothing.
How SLAs count business time
The deadline of an SLA with
business_hours: true= the time of entering the status plus the duration counted only over the calendar's working intervals. If an object entered the status outside business hours, the countdown starts at the nearest working interval.The duration of such an SLA is in hours, minutes and seconds only:
PT8H,PT30M. Days (P1D) aren't accepted — publishing the process returns thebusiness_hours_durationerror.Time is counted by the time zone's wall clock: the day of the switch to daylight saving time is one hour shorter.
After the calendar changes, deadlines of running business-time SLAs are recalculated in the background — immediately and once more two minutes later. Breaches already recorded don't change. When a deadline fires, it is checked against the current calendar once more, so an outdated deadline won't produce a false breach.
SLAs without
business_hoursare counted in calendar time; the calendar doesn't affect them.
There are no working-Saturday exceptions and no separate calendars for teams or types.
Yorumlar