Flow API: reports, SLA and business calendar

SENSEVER

The official Sensever channel: guides and API documentation for Chat, Requests, Flow, Studio, bots and messaging channels.

阅读约 21 分钟

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

POST /reports/aggregate

Counts, sums, averages, minimums and maximums with grouping

Funnel

POST /reports/funnel

Conversion by process stage for objects created in a period

Burndown

POST /reports/burndown

Remaining work for each day and the ideal line

Dashboards

GET, POST /dashboards, GET, PATCH, DELETE /dashboards/{id}

Saved sets of tiles: personal and shared

Summary across all workspaces

POST /me/reports/summary

Object counters across all of a person's workspaces; session only

Time in status by type

POST /reports/time-in-state

For each status: entries, exits, time spent, how many objects are there now

SLA summary by type

POST /reports/sla

For each SLA: met, breached, still running, share met on time

SLA breaches

POST /reports/sla/breaches

List of breaches in a period, paginated

Object's time in status

GET /reports/objects/{id}/time-in-state

The object's stays in statuses and totals

Object's SLA

GET /reports/objects/{id}/sla

The object's breaches and running deadlines

Time report

POST /reports/time

Time logged in a period by person, object or parent object

Time export

GET /reports/time/export

Time entries for a period as a CSV file

Business calendar

GET /workspace/calendar

Time zone, working hours, days off

Replace the calendar

PUT /workspace/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 own and team restrictions 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_EXPENSIVE with details.reason plan_cost or statement_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

query

object

one of the two

{"type": "<type key>", "where": {…}} — a condition in the query language

view_id

uuid

one of the two

A saved view: its condition is used (requires the view.read permission)

where

object

no

Only together with view_id: an additional condition, combined with "and"

group_by

object

no

Grouping: {"system": "…"} or {"field": "<key>"}, plus bucket for dates

metrics

array

no

1–10 metrics {"fn": "…", "field": "<key>"}. Defaults to [{"fn": "count"}]

limit

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

group_by

By what

{"system": "state"}

Status

{"system": "owner_id"}

Assignee

{"system": "created_by"}

Author

{"system": "created_at", "bucket": "week"}

Creation date; the same for updated_at

{"field": "<key>"}

A field of type string, enum, boolean, principal, multi_enum, multi_principal, tags, date, datetime

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

fn

Fields

count

No field

sum, avg

number, integer, money

min, max

number, integer, money, date, datetime

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[].key is the group value as a string: a status or person id, an option key, true/false, the interval start date; null means objects without a value. Grouping by status also includes state with its key and category.

  • Metric values are strings: decimal numbers without loss of precision, YYYY-MM-DD for dates, RFC 3339 UTC for timestamps, null if there are no values.

  • Groups are sorted by count descending, then by key. truncated: true means there were more groups than limit.

  • meta.unindexed_fields lists fields whose condition ran without an index.

  • When querying by view_id, the response also includes view_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

query or view_id

object / uuid

one of the two

Selection, as in POST /reports/aggregate. Archived objects are included: this is history

where

object

no

Only together with view_id

from, to

string

yes

Period by the object's creation date, [from, to), no longer than 366 days: a YYYY-MM-DD date or an RFC 3339 timestamp

stages

array or null

no

Status keys in funnel order, 2–20. Defaults to the statuses of the current process version in order, except the cancelled category

sum_field

string or null

no

A number, integer or money field for sums

{
  "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. entered is how many entered this exact stage.

  • conversion_from_previous is reached / reached of the previous stage, conversion_from_first is relative to the first stage, from 0 to 1; null for the first stage or when there is nothing to divide by.

  • median_seconds_from_previous is the median time between the first entries into the previous stage and this one among objects that entered both; median_pairs is how many objects it was calculated over.

  • outcomes is 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

query or view_id

object / uuid

one of the two

Selection, as in POST /reports/aggregate, for example a "Current sprint" view

where

object

no

Only together with view_id

from, to

string

yes

YYYY-MM-DD dates, both inclusive, no more than 366 days

time_zone

string or null

no

IANA time zone for day boundaries; defaults to UTC

sum_field

string or null

no

A number or integer field summed over the remaining objects (estimate, story points)

working_days

boolean or null

no

Ideal line by working days; defaults to true

{
  "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

start

Values at the start of the period (midnight of from): at, remaining, remaining_sum, total

days[].date, days[].at

The day and the moment of the values: end of day; for today, now; for future days, null

days[].remaining

Objects in the selection that are neither done nor cancelled at that moment; null for future days

days[].remaining_sum

The sum of sum_field over them, as a decimal string; null without sum_field and for future days

days[].total

Scope: objects in the selection created and not archived by that moment

days[].ideal, days[].ideal_sum

The ideal line from start.remaining (and start.remaining_sum) down to zero at the end of the last day

days[].working

Whether it is a working day; null if the report doesn't use working days

calendar

{is_default, version} — which calendar was used; null with working_days: false

  • 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 returns 422 VALIDATION_FAILED on sum_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

GET /dashboards

view.read

Create

POST /dashboards

personal — view.read; shared — view.manage

Read with tiles

GET /dashboards/{id}

view.read

Update

PATCH /dashboards/{id}

personal — author; shared, as well as changing visibility — view.manage

Delete

DELETE /dashboards/{id}

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

id

1–64 characters A-Z a-z 0-9 _ -, unique within the dashboard; chosen by the client

kind

aggregate (default), funnel or burndown

title

1–200 characters

type

Object type key

view_id

A filter view or null — all objects of the type

period

7, 30, 90, 365 (objects created in the last N days) or all

group

aggregate only: null, {"system": "state" | "owner_id" | "created_by"}, {"system": "created_at", "bucket": "week" | "month"} or {"field": "<key>", "bucket"?}

metric

aggregate: {"fn": "count"} or {"fn": "sum" | "avg", "field": "<key>"}; for funnel and burndown — {"fn": "count"}, may be omitted

from, to

burndown only: custom YYYY-MM-DD dates, both or neither, no more than 366 days

sum_field

funnel and burndown: the sum field or null

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

filter.workspace_ids

Only these workspaces, up to 100

filter.owner_user_id

me or a Flow user id — only objects with this assignee

weeks

How many recent weeks (including the current one) to return in weeks, 0–26, default 8

top_owners

How many assignees to return in owners.items, 1–20, default 8

Response:

Field

Description

as_of

Today's date in UTC — overdue status is calculated from it

totals

total, open, in_progress, done, cancelled (by status category), no_state (types without a process), overdue

workspaces[]

The same counters per workspace, with workspace (id, name, is_system)

owners.items[]

Assignees with the most objects: user_id, name, picture_url (photo from the Sensever profile or null — then draw initials), is_me, total, active (neither done nor cancelled), overdue

owners.unassigned, owners.others

Objects without an assignee and those of the remaining assignees: total, active, overdue

weeks[]

week_start (Monday, UTC), created — created during the week, done — moved to a done-category status during the week and still there

meta

workspaces_scanned, skipped_workspaces, partial — as in POST /me/objects/query

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

type

string

yes

Type key or id

from

string

yes

Period start: a YYYY-MM-DD date (00:00 UTC) or an RFC 3339 timestamp with an offset

to

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

state

{id, key, category}

entered

Entries into the status during [from, to)

completed

How many of them have already left the status (exits after to count too)

open

How many are still in the status

duration_seconds

Duration of completed stays: avg, p50, p90, max in seconds; null if there are none completed

current

How many objects are in the status now (count) and their average age in the status (avg_age_seconds)

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 (null for 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

sla_key, state

The SLA and its status

duration

ISO 8601 duration (business time if business_hours)

business_hours

Whether it is counted in business time

entered

Entries into the status during the period on versions with this SLA

met

Left without a breach

breached

Breached

open

Still in the status and not breached

compliance

Share met on time: met / (met + breached), from 0 to 1; null if there are no completed entries

duration and business_hours are taken from the newest version with this SLA.

Breaches

POST /reports/sla/breaches:

Field

Type

Required

Description

type

string

yes

Object type

from, to

string

yes

Period by breach time breached_at

sla_key

string or null

no

Only this SLA

page

object

no

{"size": 1–200, default 50, "cursor": "…"}

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

timezone

string

yes

IANA time zone, for example Europe/Moscow

week

object

yes

Days mon … sun: up to 4 non-overlapping intervals {"from": "HH:MM", "to": "HH:MM"} in local time. to can be 24:00. A missing day means no working time

holidays

array

no

Up to 500 non-working dates YYYY-MM-DD in the calendar's time zone

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 the business_hours_duration error.

  • 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_hours are counted in calendar time; the calendar doesn't affect them.

There are no working-Saturday exceptions and no separate calendars for teams or types.

评论

作者