Flow API: time tracking

SENSEVER

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

11 min read

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

flw_… key scope

Object time: entries and totals

GET /objects/{id}/time

object.read

object:read

Log time

POST /objects/{id}/time

object.update; for another member, also workspace.manage

object:update; workspace:manage

Change an entry

PATCH /time-entries/{id}

your own — object.update; someone else's — workspace.manage

object:update or workspace:manage

Delete an entry

DELETE /time-entries/{id}

same as changing

same as changing

My timer

GET /time/timer

workspace member

—

Start the timer

POST /time/timer

object.update

object:update

Stop the timer

POST /time/timer/stop

your own timer

—

Totals for the "Spent" column

POST /time/totals

object.read

object:read

Time report

POST /reports/time

object.read

object:read

Export entries to CSV

GET /reports/time/export

object.read

object:read

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

id

UUID

The entry

object_id

UUID

The object

principal_id

UUID

Whose time this is

started_at

string

When the work started, RFC 3339 UTC. This date determines the day and the report period the entry falls into

duration_seconds

integer

Duration, 1–86,400 seconds (up to 24 hours)

comment

string

Comment, up to 2000 characters; an empty string means no comment

billable

boolean

Billable time

source

string

manual — logged manually, timer — logged with the timer

version

integer

Entry version, increments with each change

can_manage

boolean

Whether you can change or delete the entry

created_by, created_at


Who logged it and when (an administrator can log another member's time)

updated_by, updated_at


Who last changed it and when

Log time

POST /objects/{id}/time:

Field

Type

Required

Description

started_at

string

yes

Start of work: RFC 3339 with an offset, for example 2026-09-26T10:00:00+03:00. Not earlier than 2000 and not later than 24 hours from now

duration_seconds

integer

yes

1–86,400

comment

string

no

Up to 2000 characters, leading and trailing spaces are trimmed

billable

boolean

no

Defaults to false

principal_id

UUID

no

Log time for another active member. Requires workspace.manage

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

total_seconds, billable_seconds, entry_count

Totals across all of the object's entries

by_person[]

Per person: principal_id, total_seconds, billable_seconds, entries

children

Time of child objects you can read: total_seconds, billable_seconds, objects — how many of them have entries

rollup_seconds

Own time plus the children's time

entries[]

Entries, newest first, at most 100; entries_truncated: true means there are more (totals cover all of them)

can_log

Whether you can log time on this object

timer

Your timer, if it's running on this object, otherwise null

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/timer returns {"timer": {...}} or {"timer": null}. A timer has object_id, object_title, object_type, started_at, elapsed_seconds, comment, billable. If the object is no longer visible to you, object_title and object_type are null, but you can still stop the timer.

  • POST /time/timer with {"object_id": "…", "comment": "…", "billable": false} starts the timer (requires object.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 in stopped (or null if it ran for less than a minute). If a timer is already running on this object, it's returned unchanged. Response 200 is {"timer": {...}, "stopped": TimeEntry | null}.

  • POST /time/timer/stop stops the timer and creates an entry with source: "timer": the start is the time it was started, the duration is how much time has passed. comment and billable in 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

from

string

yes

Start of the period, inclusive, RFC 3339 with an offset

to

string

yes

End of the period, exclusive; at most 366 days after from

group_by

string

no

person (default), object or relation

relation

string

for relation

Key of a many-to-one or one-to-many relation, for example task_project: the groups are the parent objects

billable

boolean or null

no

Only billable (true) or only non-billable (false)

type

string or null

no

Object type key

principal_id

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[].key is the id of the member (person), the object (object) or the parent object (relation). label is the person's name or the object's title, type is 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: true means there were more). The totals total_seconds, billable_seconds, entry_count, group_count cover 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.csv
  • The file is UTF-8 with a BOM, comma-separated, with CRLF line endings, named time-<first day>-<last day>.csv.

  • Columns: date, start (in the tz zone), person, object, type, the parent's title (only with relation; the header is the relation name), hours (hours with two decimals: 5400 seconds is 1.50), billable, comment, object_id, entry_id.

  • At most 50,000 rows; if there are more entries, the response header X-Flow-Export-Truncated: true is 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 tz returns invalid on the tz field.

Errors

HTTP

error.code

When

404

OBJECT_NOT_FOUND

The object doesn't exist or you can't read it

404

NOT_FOUND

The entry doesn't exist, is on an invisible object, or no timer is running

403

PERMISSION_DENIED

No permission to change the object or someone else's entry, or to log time for another member

409

OBJECT_ARCHIVED

The object is archived: time can't be logged or changed

409

OBJECT_VERSION_CONFLICT

The entry's expected_version is outdated

422

VALIDATION_FAILED

Invalid fields: invalid, out_of_range (started_at), required, too_many, unknown_principal and report codes

What's next

Comments

Authors