> ## 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.

# Time Entries

> API reference for Essal Project time entries — manual logging, start/stop timers, and reporting.

## List Time Entries

`GET /v1/project/time-entries`

**Query Parameters**

| Parameter    | Type   | Description                    |
| ------------ | ------ | ------------------------------ |
| `project_id` | string | Filter by project              |
| `task_id`    | string | Filter by task                 |
| `user_id`    | string | Filter by user                 |
| `date_from`  | date   | Start of date range (ISO 8601) |
| `date_to`    | date   | End of date range (ISO 8601)   |

***

## Create a Time Entry

`POST /v1/project/time-entries`

```json theme={null}
{
  "task_id": "task_01HXYZTASK1",
  "user_id": "usr_01HXYZ1111",
  "duration_seconds": 5400,
  "date": "2026-07-10",
  "note": "Completed component inventory"
}
```

***

## Start a Timer

`POST /v1/project/time-entries/start`

```json theme={null}
{ "task_id": "task_01HXYZTASK1", "user_id": "usr_01HXYZ1111" }
```

**Response**

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

***

## Stop a Timer

`POST /v1/project/time-entries/stop`

```json theme={null}
{ "timer_id": "tmr_01HXYZTMR1", "note": "Finished audit" }
```

A time entry is automatically created with the elapsed duration.

***

## Update a Time Entry

`PATCH /v1/project/time-entries/{id}`

```json theme={null}
{ "duration_seconds": 3600, "note": "Corrected logged time" }
```

***

## Get Time Report

`GET /v1/project/projects/{project_id}/time-report`

**Query Parameters**

| Parameter  | Type   | Description                              |
| ---------- | ------ | ---------------------------------------- |
| `period`   | string | Month (`2026-07`) or quarter (`2026-Q3`) |
| `group_by` | enum   | `user` (default) or `task`               |
| `export`   | enum   | `json` (default) or `csv`                |

***

## Delete a Time Entry

`DELETE /v1/project/time-entries/{id}`