Python SDK: Time Entries

Create a Time Entry

entry = client.time_entries.create(
    project_id="prj_abc",
    task_id="tsk_001",
    spent_date="2026-03-06",
    hours=1.5,
    notes="Refactored authentication module",
    source="agent",
    metadata={
        "agent_id": "review-bot-01",
        "agent_type": "claude-code",
        "session_id": "550e8400-e29b-41d4-a716-446655440000",
        "model": "claude-opus-4-6",
    },
)

Start a Running Timer

from datetime import date

timer = client.time_entries.start_timer(
    project_id="prj_abc",
    task_id="tsk_001",
    spent_date=str(date.today()),
    source="agent",
    replace_running=True,
    metadata={
        "agent_id": "review-bot-01",
        "session_id": "550e8400-e29b-41d4-a716-446655440000",
    },
)

Omit started_time for a current, exact server-side start. started_time and ended_time are HH:mm workspace-time strings, not ISO timestamps. If another timer is already running, the API returns 409 Conflict unless you pass replace_running=True.

Stop a Timer

client.time_entries.stop_timer(timer.id, notes="Completed code review")

The API calculates elapsed duration server-side from the timer start state.

Restart a Timer

client.time_entries.restart_timer(timer.id, replace_running=True)

List Time Entries

# All agent entries for a project this week
entries = client.time_entries.list(
    source="agent",
    project_id="prj_abc",
    from_date="2026-03-01",
    to_date="2026-03-06",
)

for entry in entries:
    print(f"{entry.spent_date}: {entry.hours}h — {entry.notes}")

Delete a Time Entry

client.time_entries.delete("te_abc123")