> ## Documentation Index
> Fetch the complete documentation index at: https://developers.essal.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Track Time

> Log time entries against tasks in Essal Project, use the start/stop timer API, and generate time reports.

Essal Project includes built-in time tracking. Team members can log time manually or use the real-time start/stop timer. Time entries are linked to tasks and roll up to project-level reports.

## Logging a Manual Time Entry

```bash theme={null}
POST /v1/project/time-entries
{
  "task_id": "task_01HXYZTASK1",
  "user_id": "usr_01HXYZ1111",
  "duration_seconds": 5400,
  "date": "2026-07-10",
  "note": "Completed typography token audit"
}
```

`duration_seconds` is always stored in seconds. The dashboard displays it formatted as `h:mm`.

## Using the Start/Stop Timer

Start a timer against a task:

```bash theme={null}
POST /v1/project/time-entries/start
{
  "task_id": "task_01HXYZTASK1",
  "user_id": "usr_01HXYZ1111"
}
```

```json theme={null}
{
  "timer_id": "tmr_01HXYZTMR1",
  "started_at": "2026-07-10T14:00:00Z",
  "status": "running"
}
```

Stop the timer and save the entry:

```bash theme={null}
POST /v1/project/time-entries/stop
{
  "timer_id": "tmr_01HXYZTMR1",
  "note": "Worked on component inventory"
}
```

The elapsed time is calculated server-side and a time entry is created automatically.

<Note>
  Only one timer can run at a time per user. Starting a new timer automatically stops any currently running timer and saves that entry first.
</Note>

## Listing Time Entries

```bash theme={null}
GET /v1/project/time-entries?project_id=proj_01HXYZ9876&user_id=usr_01HXYZ1111&date_from=2026-07-01&date_to=2026-07-31
```

## Time Reports

Generate a time summary report for a project or user over a given period:

```bash theme={null}
GET /v1/project/projects/proj_01HXYZ9876/time-report?period=2026-07
```

```json theme={null}
{
  "project_id": "proj_01HXYZ9876",
  "period": "2026-07",
  "total_seconds": 432000,
  "by_user": [
    { "user_id": "usr_01HXYZ1111", "display_name": "Sam Chen", "total_seconds": 216000 },
    { "user_id": "usr_01HXYZ2222", "display_name": "Priya Nair", "total_seconds": 216000 }
  ],
  "by_task": [
    { "task_id": "task_01HXYZTASK1", "title": "Design system audit", "total_seconds": 108000 }
  ]
}
```

<Tip>
  Use the `export` parameter (`?export=csv`) to download the report as a CSV file for use in spreadsheets or external billing systems.
</Tip>