Time Logs API — Task Timers and Manual Time Entries - Workforce Intelligence & Execution OS

The Time Logs API captures how long employees spend on individual tasks. It supports two complementary entry modes: a timer-based flow that measures elapsed time precisely from start through any pauses to stop, and a manual entry flow for logging time blocks that were worked without an active timer — for example, when recording offline work retroactively. All time logs are linked to a specific task and contribute to actual_duration_minutes on that task, which feeds workload analytics and burndown calculations.

All endpoints are prefixed with /api/v1/time-logs and require an Authorization: Bearer <token> header. All timestamps are returned in UTC ISO-8601 format with a Z suffix.

Enum Reference

Log Source Type

Value	Description
`timer`	Created automatically when a running timer session is stopped via `POST /time-logs/stop`. Duration is computed from accumulated running intervals.
`manual`	Created explicitly via `POST /time-logs/manual` by supplying `started_at` and `ended_at` timestamps.

Log Status

Value	Description
`active`	Timer is currently running (timer-source logs only).
`completed`	Timer has been stopped or manual log has been saved.
`invalid`	Log was flagged by the system (e.g. overlapping or suspicious duration).

Timer Session Status

Value	Description
`running`	Timer is actively counting.
`paused`	Timer is paused; `pause_reason` is set.
`completed`	Timer session has been finalised and converted to a TimeLog.

Timer Pause Reason

Value	Description
`manual_pause`	User manually paused the timer.
`attendance_checkout`	Timer was auto-paused when the user checked out of their attendance session.
`break_started`	Timer was auto-paused when an attendance break began.
`system`	System-initiated pause (e.g. server maintenance or session expiry).

POST /time-logs/start

Start a new timer session on the specified task. Only one active timer is permitted per user at a time. The timer begins tracking elapsed seconds from the moment this call succeeds. Auth: Any authenticated user. The task must be assigned to the caller, or the caller must be a manager/admin.

Request Body

task_id

uuid

required

UUID of the task to begin timing.

Response Fields

Returns a TaskTimerRead object representing the active timer session.

uuid

required

Unique timer session identifier.

task_id

uuid

required

Task this timer is running against.

task_title

string

Resolved task name.

project_title

string

Resolved parent project name.

user_id

uuid

required

UUID of the employee who owns this timer.

status

string

required

Timer state: running, paused, or completed.

started_at

datetime

required

UTC timestamp of the first start.

last_resumed_at

datetime

required

UTC timestamp of the most recent resume (equals started_at on first start).

paused_at

datetime

UTC timestamp of when the timer was last paused; null when running.

accumulated_seconds

integer

required

Total seconds accumulated across all running intervals, excluding pause time.

pause_reason

string

Why the timer was paused: manual_pause, attendance_checkout, break_started, or system.

created_at

datetime

required

Record creation timestamp.

updated_at

datetime

required

Last update timestamp.

A timer is automatically paused when the user checks out of an attendance session or starts an attendance break. Call POST /time-logs/stop before ending your work day to finalise the log.

Example

curl -X POST "https://api.example.com/api/v1/time-logs/start" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }'

POST /time-logs/pause

Pause the active timer session for the specified task. The timer stops accumulating seconds until it is resumed. Auth: Any authenticated user (must own the active timer).

Request Body

task_id

uuid

required

UUID of the task whose active timer should be paused.

Response Fields

Returns the updated TaskTimerRead with status: "paused" and pause_reason: "manual_pause". See POST /time-logs/start for the full field list.

Example

curl -X POST "https://api.example.com/api/v1/time-logs/pause" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }'

POST /time-logs/resume

Resume a paused timer session for the specified task, continuing to accumulate seconds from the current moment. Auth: Any authenticated user (must own the paused timer).

Request Body

task_id

uuid

required

UUID of the task whose paused timer should be resumed.

Response Fields

Returns the updated TaskTimerRead with status: "running" and pause_reason cleared to null.

Example

curl -X POST "https://api.example.com/api/v1/time-logs/resume" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }'

POST /time-logs/stop

Stop the active timer session for the specified task and finalise it into a permanent TimeLog record. The duration is computed from all accumulated running intervals and written to the task’s actual_duration_minutes. Auth: Any authenticated user (must own the active timer).

Request Body

task_id

uuid

required

UUID of the task whose active timer should be stopped.

notes

string

Optional notes describing what was accomplished during this session.

Response Fields

Returns a TimeLogRead object with source_type: "timer" and status: "completed".

uuid

required

Unique time log identifier.

task_id

uuid

required

Task this log is recorded against.

task_title

string

Resolved task name for display.

user_id

uuid

required

UUID of the employee who worked.

user_name

string

Resolved employee display name.

project_title

string

Resolved parent project name.

started_at

datetime

required

UTC start of the first timer interval.

ended_at

datetime

UTC end of the last interval (set when timer is stopped).

duration_minutes

integer

Total worked minutes (sum of all running intervals, rounded down).

source_type

string

required

timer for this endpoint.

notes

string

Notes provided at stop time.

status

string

required

completed on successful stop.

created_at

datetime

required

Record creation timestamp.

updated_at

datetime

required

Last update timestamp.

Example

curl -X POST "https://api.example.com/api/v1/time-logs/stop" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "notes": "Completed OAuth token exchange and unit tests."
  }'

Complete Timer Lifecycle Example

Step 1 — Start

curl -X POST "https://api.example.com/api/v1/time-logs/start" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"task_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"}'

# Response: TaskTimerRead with status "running"

Step 2 — Pause (optional)

curl -X POST "https://api.example.com/api/v1/time-logs/pause" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"task_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"}'

# Response: TaskTimerRead with status "paused"

Step 3 — Resume (optional)

curl -X POST "https://api.example.com/api/v1/time-logs/resume" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"task_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"}'

# Response: TaskTimerRead with status "running"

Step 4 — Stop and save log

curl -X POST "https://api.example.com/api/v1/time-logs/stop" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "notes": "Initial implementation complete."
  }'

# Response: TimeLogRead with source_type "timer", duration_minutes computed

GET /time-logs/active-timer

Return the authenticated user’s currently active or paused timer session, or null if no timer is running. Auth: Any authenticated user.

Response Fields

Returns a single TaskTimerRead object, or null. See POST /time-logs/start for the full field list.

Example

curl -X GET "https://api.example.com/api/v1/time-logs/active-timer" \
  -H "Authorization: Bearer <token>"

POST /time-logs/manual

Directly record a time entry by supplying explicit start and end timestamps. Use this when you worked on a task without an active timer — for example, during offline work, a meeting, or retrospective logging. Auth: Any authenticated user.

Request Body

task_id

uuid

required

UUID of the task this time entry applies to.

started_at

datetime

required

UTC start timestamp of the work block (ISO-8601).

ended_at

datetime

required

UTC end timestamp. Must be strictly after started_at.

notes

string

Optional description of the work performed.

Response Fields

Returns a TimeLogRead object with source_type: "manual".

The system validates that ended_at > started_at. Reversed or identical timestamps return 400 Bad Request.

Example

curl -X POST "https://api.example.com/api/v1/time-logs/manual" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "started_at": "2024-07-10T10:00:00Z",
    "ended_at": "2024-07-10T12:30:00Z",
    "notes": "Reviewed design specs and prepared technical breakdown."
  }'

GET /time-logs/me

Retrieve the authenticated employee’s full time log history across all tasks and projects, ordered by started_at descending. Auth: Any authenticated user.

Response Fields

Returns an array of TimeLogRead objects. See POST /time-logs/stop for the full field list.

Use the source_type field to visually distinguish timer-tracked entries from manually entered ones in a personal timesheet view.

Example

curl -X GET "https://api.example.com/api/v1/time-logs/me" \
  -H "Authorization: Bearer <token>"

Example Response

[
  {
    "id": "a1b2c3d4-0000-0000-0000-000000000001",
    "task_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "task_title": "Implement OAuth2 login flow",
    "user_id": "b5c6d7e8-0000-0000-0000-000000000002",
    "user_name": "Ayesha Raza",
    "project_title": "Customer Portal Redesign Q3",
    "started_at": "2024-07-10T09:00:00Z",
    "ended_at": "2024-07-10T11:45:00Z",
    "duration_minutes": 165,
    "source_type": "timer",
    "notes": "Completed token exchange and added refresh logic.",
    "status": "completed",
    "created_at": "2024-07-10T11:45:02Z",
    "updated_at": "2024-07-10T11:45:02Z"
  }
]

GET /time-logs/team

Retrieve time logs for the authenticated user’s team. Managers see their direct reports’ logs; Admins and HR see the entire organisation. Auth: Any authenticated user. Results are RBAC-scoped.

Response Fields

Returns an array of TimeLogRead objects.

Example

curl -X GET "https://api.example.com/api/v1/time-logs/team" \
  -H "Authorization: Bearer <token>"

Standard Error Response

{
  "detail": "You already have an active timer session. Stop it before starting a new one."
}

Common HTTP status codes for this resource: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict.

Overview

Endpoints

Time Logs API — Task Timers and Manual Time Entries

Enum Reference

Log Source Type

Log Status

Timer Session Status

Timer Pause Reason

POST /time-logs/start

Request Body

Response Fields

POST /time-logs/pause

Request Body

Response Fields

POST /time-logs/resume

Request Body

Response Fields

POST /time-logs/stop

Request Body

Response Fields

Complete Timer Lifecycle Example

GET /time-logs/active-timer

Response Fields

POST /time-logs/manual

Request Body

Response Fields

GET /time-logs/me

Response Fields

Example Response

GET /time-logs/team

Response Fields

Standard Error Response

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​Enum Reference

​Log Source Type

​Log Status

​Timer Session Status

​Timer Pause Reason

​POST /time-logs/start

​Request Body

​Response Fields

​POST /time-logs/pause

​Request Body

​Response Fields

​POST /time-logs/resume

​Request Body

​Response Fields

​POST /time-logs/stop

​Request Body

​Response Fields

​Complete Timer Lifecycle Example

​GET /time-logs/active-timer

​Response Fields

​POST /time-logs/manual

​Request Body

​Response Fields

​GET /time-logs/me

​Response Fields

​Example Response

​GET /time-logs/team

​Response Fields

​Standard Error Response

Build docs developers (and LLMs) love

Enum Reference

Log Source Type

Log Status

Timer Session Status

Timer Pause Reason

POST /time-logs/start

Request Body

Response Fields

POST /time-logs/pause

Request Body

Response Fields

POST /time-logs/resume

Request Body

Response Fields

POST /time-logs/stop

Request Body

Response Fields

Complete Timer Lifecycle Example

GET /time-logs/active-timer

Response Fields

POST /time-logs/manual

Request Body

Response Fields

GET /time-logs/me

Response Fields

Example Response

GET /time-logs/team

Response Fields

Standard Error Response