Skip to content
dotby Docs

Time entries

Time tracking is self-report per member: these endpoints read YOUR OWN entries and running timer only — there is no all-members read.

List time entries

Section titled “List time entries”

List YOUR OWN time entries in a workspace. Legacy from/to (ms epoch, on entry start) remain supported. Alternatively pass a server-resolved calendar period; custom requires fromDate and toDate, and calendar pages return nextCursor, complete, and the resolved range. Optional issueId narrows to one Task. Newest first and money-blind. capped: true means more rows exist or the bounded result is incomplete.

GET /v1/workspaces/{workspaceId}/time-entries

Terminal window
curl -H "Authorization: Bearer $DOTBY_TOKEN" \
  "https://api.dotby.app/v1/workspaces/acme/time-entries?limit=25"

Response: a list envelope { data, has_more, next_cursor }. While has_more is true, pass next_cursor back as cursor to get the next page.

Get running timer

Section titled “Get running timer”

Get YOUR current active timer in a workspace (running or paused), or null when none is active. This legacy v1 read returns a 409 timer_stack_active conflict when more than one timer is open; use get_running_timers for the plural stack. No rate or amount is stored.

GET /v1/workspaces/{workspaceId}/time-entries/running

Terminal window
curl -H "Authorization: Bearer $DOTBY_TOKEN" \
  "https://api.dotby.app/v1/workspaces/acme/time-entries/running"

Response: the resulting object as JSON.

Get running timers

Section titled “Get running timers”

Get YOUR full active timer stack. Separates running and paused timers, supplies runningCount/openCount, and reports liveWorkedMs as distinct wall-clock time (overlaps count once). Each timer includes its activity, segments, classification, note, and linked Tasks; no rate or amount is stored.

GET /v1/v2/workspaces/{workspaceId}/time-entries/running

Terminal window
curl -H "Authorization: Bearer $DOTBY_TOKEN" \
  "https://api.dotby.app/v1/v2/workspaces/acme/time-entries/running"

Response: the resulting object as JSON.

Errors

Section titled “Errors”

Every error is an RFC 9457 application/problem+json body with a machine-stable code. Branch on the code, not the message:

  • 401 — unauthenticated / invalid_token: the bearer token is missing, expired, or revoked. Re-authenticate; do not retry as-is.
  • 403 — insufficient_scope / forbidden / upgrade_required: the token works but may not do this. upgrade_required means the workspace is not on Pro.
  • 404 — not_found_or_forbidden: the resource does not exist for this token. Never probe for existence.
  • 409 — idempotency_conflict: same Idempotency-Key, different body. Mint a new key.
  • 429 — rate_limited: back off for the number of seconds in Retry-After, then retry.
  • 400 — validation_failed: the request shape is wrong. Fix the request; retrying unchanged will fail again.