Flow API: time tracking
In Flow, time is logged on any object: manually (how long and when you worked) or with a timer. This article covers time entries, the timer, totals for the "Spent" column, and the time report with CSV export.
General rules — base URL, keys, the X-Workspace-Id and Idempotency-Key headers, the error format — are in Flow API: basics. For how time tracking looks in the interface, see Flow: time tracking.
Methods
Method | Request | Permission |
|
|---|---|---|---|
Object time: entries and totals |
|
|
|
Log time |
|
|
|
Change an entry |
| your own — |
|
Delete an entry |
| same as changing | same as changing |
My timer |
| workspace member | — |
Start the timer |
|
|
|
Stop the timer |
| your own timer | — |
Totals for the "Spent" column |
|
|
|
Time report |
|
|
|
Export entries to CSV |
|
|
|
Paths are relative to https://flow.sensever.com/v1. The methods work within one workspace: with a session and X-Workspace-Id, with a Sensever platform key, or with a flw_… workspace key; the old gateway https://sensever.com/api/v1/flow (shut down on 13.10.2026) doesn't pass them through, https://api.sensever.com/v1/flow does. Time is logged by a workspace member — the one the key acts on behalf of. There's no separate time tracking permission: anyone who can change an object can log their own time on it.
Changes (POST /objects/{id}/time, PATCH and DELETE /time-entries/{id}, POST /time/timer, POST /time/timer/stop) accept an optional Idempotency-Key. POST /time/totals and POST /reports/time only read and don't use the key, but they're POST: a "Read-only" platform key gets 403 with details.reason = read_only_key on them. GET /reports/time/export is available to it.
Entries and the timer don't produce webhook events; every creation, change and deletion of an entry goes to the audit log (time_entry.create, time_entry.update, time_entry.delete).
Time entry
TimeEntry
Field | Type | Description |
|---|---|---|
| UUID | The entry |
| UUID | The object |
| UUID | Whose time this is |
| string | When the work started, RFC 3339 UTC. This date determines the day and the report period the entry falls into |
| integer | Duration, 1–86,400 seconds (up to 24 hours) |
| string | Comment, up to 2000 characters; an empty string means no comment |
| boolean | Billable time |
| string |
|
| integer | Entry version, increments with each change |
| boolean | Whether you can change or delete the entry |
| Who logged it and when (an administrator can log another member's time) | |
| Who last changed it and when |
Log time
POST /objects/{id}/time:
Field | Type | Required | Description |
|---|---|---|---|
| string | yes | Start of work: RFC 3339 with an offset, for example |
| integer | yes | 1–86,400 |
| string | no | Up to 2000 characters, leading and trailing spaces are trimmed |
| boolean | no | Defaults to |
| UUID | no | Log time for another active member. Requires |
curl -X POST https://flow.sensever.com/v1/objects/$OBJECT_ID/time \
-H "Authorization: Bearer $SENSEVER_API_KEY" \
-H "X-Workspace-Id: $WORKSPACE_ID" \
-H "Idempotency-Key: time-7f3a-2026-09-26-1" \
-H "Content-Type: application/json" \
-d '{
"started_at": "2026-09-26T10:00:00+03:00",
"duration_seconds": 5400,
"comment": "Call with the client",
"billable": true
}'Response 201 is the entry:
{
"id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6f40",
"object_id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b72",
"principal_id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b74",
"started_at": "2026-09-26T07:00:00Z",
"duration_seconds": 5400,
"comment": "Call with the client",
"billable": true,
"source": "manual",
"version": 1,
"can_manage": true,
"created_by": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b74",
"created_at": "2026-09-26T08:31:12Z",
"updated_by": null,
"updated_at": "2026-09-26T08:31:12Z"
}After a network error, repeat the request with the same Idempotency-Key: without it, a repeat creates a second entry.
Change and delete
PATCH /time-entries/{id} changes the fields you pass: started_at, duration_seconds, comment, billable. The expected_version field — the entry's current version — is required: if the entry was changed in the meantime, the response is 409 OBJECT_VERSION_CONFLICT with details.expected_version and details.actual_version. A request with no changes returns the entry as is and doesn't increment the version. You can't change whose work it is or which object it's on — delete the entry and create a new one.
{"expected_version": 1, "duration_seconds": 3600, "billable": false}DELETE /time-entries/{id} deletes the entry and returns {"id": "…", "deleted": true}; a repeat returns 404 NOT_FOUND. The history stays in the audit log.
Anyone who can change the object (object.update) can change their own entry; a member with workspace.manage (administrator, owner) can change any entry. An entry on an object you can't read returns 404 NOT_FOUND; an archived object returns 409 OBJECT_ARCHIVED: time on it can't be changed.
Object time
GET /objects/{id}/time returns the object's entries and totals:
Field | Description |
|---|---|
| Totals across all of the object's entries |
| Per person: |
| Time of child objects you can read: |
| Own time plus the children's time |
| Entries, newest first, at most 100; |
| Whether you can log time on this object |
| Your timer, if it's running on this object, otherwise |
Child objects are objects on the "many" side of a many-to-one (or one-to-many) relation where this object is on the "one" side, one level deep: a project's tasks, a task's subtasks. An object you can't read returns 404 OBJECT_NOT_FOUND.
Timer
A member can have at most one running timer in a workspace.
GET /time/timerreturns{"timer": {...}}or{"timer": null}. A timer hasobject_id,object_title,object_type,started_at,elapsed_seconds,comment,billable. If the object is no longer visible to you,object_titleandobject_typearenull, but you can still stop the timer.POST /time/timerwith{"object_id": "…", "comment": "…", "billable": false}starts the timer (requiresobject.update, and the object must not be archived). If a timer is already running on another object, it's stopped first and logged — that entry comes back instopped(ornullif it ran for less than a minute). If a timer is already running on this object, it's returned unchanged. Response200is{"timer": {...}, "stopped": TimeEntry | null}.POST /time/timer/stopstops the timer and creates an entry withsource: "timer": the start is the time it was started, the duration is how much time has passed.commentandbillablein the body replace the values set at start;{"discard": true}stops it without logging. The response is{"entry": TimeEntry | null, "discarded": false, "capped": false}.
curl -X POST https://flow.sensever.com/v1/time/timer/stop \
-H "Authorization: Bearer $SENSEVER_API_KEY" \
-H "X-Workspace-Id: $WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{"comment": "Form layout", "billable": true}'Stopping rules:
a timer shorter than a minute isn't logged:
entry: null,discarded: true;a timer longer than 24 hours is logged as 24 hours:
capped: true;permissions on the object aren't checked on stop — they were checked at start, so the time isn't lost if the object has since been archived or your permission was revoked;
no timer —
404 NOT_FOUND.
Totals for a table
POST /time/totals with {"object_ids": [...]} (up to 200 ids) returns, for each object you can read, its own time plus the time of its child objects (like rollup_seconds). This is how the interface fills the "Spent" column ($time_spent in a view).
{"items": [{"object_id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b72", "total_seconds": 12600, "billable_seconds": 5400}]}The order matches the request. Objects that don't exist or that you can't read are absent from the response. More than 200 ids returns 422 VALIDATION_FAILED with code too_many.
Time report
POST /reports/time returns time for a period from entries on objects you can read.
Field | Type | Required | Description |
|---|---|---|---|
| string | yes | Start of the period, inclusive, RFC 3339 with an offset |
| string | yes | End of the period, exclusive; at most 366 days after |
| string | no |
|
| string | for | Key of a many-to-one or one-to-many relation, for example |
| boolean or null | no | Only billable ( |
| string or null | no | Object type key |
| UUID or null | no | Only this member's time |
An entry belongs to a period by its started_at. Day boundaries are set by the client: pass midnight in your time zone, for example 2026-09-01T00:00:00+03:00.
curl -X POST https://flow.sensever.com/v1/reports/time \
-H "Authorization: Bearer $SENSEVER_API_KEY" \
-H "X-Workspace-Id: $WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"from": "2026-09-01T00:00:00+03:00",
"to": "2026-10-01T00:00:00+03:00",
"group_by": "relation",
"relation": "task_project",
"billable": true
}'{
"from": "2026-08-31T21:00:00Z",
"to": "2026-09-30T21:00:00Z",
"group_by": "relation",
"relation": "task_project",
"billable": true,
"total_seconds": 162000,
"billable_seconds": 162000,
"entry_count": 58,
"group_count": 3,
"rows": [
{"key": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6c10", "label": "Client website", "type": "project", "total_seconds": 108000, "billable_seconds": 108000, "entries": 41},
{"key": null, "label": null, "type": null, "total_seconds": 7200, "billable_seconds": 7200, "entries": 2}
],
"truncated": false
}rows[].keyis the id of the member (person), the object (object) or the parent object (relation).labelis the person's name or the object's title,typeis the object's type key.When grouping by relation, the parent's own time goes to the parent itself; entries whose object has no parent, or whose parent isn't visible to you, are collected in a row with
key: null.Groups are sorted by time, descending, at most 1000 (
truncated: truemeans there were more). The totalstotal_seconds,billable_seconds,entry_count,group_countcover all groups.
Errors return 422 VALIDATION_FAILED with details.fields[{field, code, messages}]: invalid (format), before_from (to isn't later than from), period_too_long, required (relation for grouping by relation), unknown_type, unknown_relation, not_hierarchical (the relation is neither many-to-one nor one-to-many).
CSV export
GET /reports/time/export returns the report's entries as a file: the same from, to, relation, billable (true or false), type, principal_id in the query string, plus tz — the IANA time zone for dates and times in the file (UTC by default). There's no grouping: one row is one entry, ordered by start time.
curl -G https://flow.sensever.com/v1/reports/time/export \
-H "Authorization: Bearer $SENSEVER_API_KEY" \
-H "X-Workspace-Id: $WORKSPACE_ID" \
--data-urlencode "from=2026-09-01T00:00:00+03:00" \
--data-urlencode "to=2026-10-01T00:00:00+03:00" \
--data-urlencode "relation=task_project" \
--data-urlencode "tz=Europe/Moscow" \
-o time.csvThe file is UTF-8 with a BOM, comma-separated, with CRLF line endings, named
time-<first day>-<last day>.csv.Columns:
date,start(in thetzzone),person,object,type, the parent's title (only withrelation; the header is the relation name),hours(hours with two decimals: 5400 seconds is1.50),billable,comment,object_id,entry_id.At most 50,000 rows; if there are more entries, the response header
X-Flow-Export-Truncated: trueis set — narrow the period or filters.Text that starts with
=,+,-or@gets a leading apostrophe so a spreadsheet doesn't treat it as a formula.Errors are the same as for the report; an invalid
tzreturnsinvalidon thetzfield.
Errors
HTTP |
| When |
|---|---|---|
404 |
| The object doesn't exist or you can't read it |
404 |
| The entry doesn't exist, is on an invisible object, or no timer is running |
403 |
| No permission to change the object or someone else's entry, or to log time for another member |
409 |
| The object is archived: time can't be logged or changed |
409 |
| The entry's |
422 |
| Invalid fields: |
What's next
Flow: time tracking — the timer, entries and the "Time" report in the interface.
Flow API: subtasks, checklists and recurrence — subtasks whose time adds up in the parent.
Flow API: reports, SLA and business calendar — other reports.
Flow API: basics — keys, headers, errors and limits.
Commentaires