# List personal time entries

Source: https://www.tracktimer.app/docs/list-time-entries

Read personal workspace history with project filtering and cursor pagination.

`GET /api/v1/time-entries`

Required scope: `timers:read`

Returns the key user's entries in its workspace: active, completed, and voided. Historical entries include archived projects or projects the user is no longer assigned to. This is not organization-wide history.

## Request

Requires bearer authentication and `timers:read`. No body. Optional query parameters:

- `projectId`: project UUID filtering the user's history.
- `limit`: integer from 1 through 100, default 20.
- `cursor`: opaque `nextCursor` from the preceding page; omit initially. Maximum 1,024 base64url characters.

There are no date, status, offset, or user filters. Unknown parameters are not supported filters. Entries sort by start time descending, then ID descending.

```sh
curl "https://www.tracktimer.app/api/v1/time-entries?limit=20&projectId=22222222-2222-4222-8222-222222222222" \
  --header "Authorization: Bearer $TRACKTIMER_API_KEY"
```

## Response — 200

- `entries`: array, possibly empty.
- `nextCursor`: next-page string, or `null` if none was found.

Each entry contains:

- `id`: entry UUID.
- `clientId`, `projectId`: client and project UUIDs.
- `clientName`, `projectName`: nonempty display names.
- `status`: `"active"`, `"completed"`, or `"voided"`.
- `billable`: boolean. Nonbillable entries can still produce member earnings.
- `note`: string up to 500 characters, or `null`.
- `startedAt`: ISO 8601 timestamp with timezone offset, normally UTC `Z`.
- `endedAt`: timestamp or `null` for an unfinished entry.
- `durationSeconds`: nonnegative integer recorded duration, or `null` if not finalized. This is not a live elapsed value.
- `payRateCents`: nonnegative integer hourly pay rate in cents, snapshotted on the entry.
- `earnings`: decimal-dollar string or `null`. Completed entry earnings use duration and pay rate independently of billability. Active entries and entries without duration return null. Voided entries with recorded duration return `"0"`.
- `currency`: always `"USD"`.

Duration and pay-rate integers are bounded by 2,147,483,647. Earnings strings have up to 12 fractional places, not necessarily two. Preserve decimal precision. Client billing rates and organizational profit fields are not included.

```json
{
  "entries": [
    {
      "id": "33333333-3333-4333-8333-333333333333",
      "clientId": "11111111-1111-4111-8111-111111111111",
      "clientName": "Northstar",
      "projectId": "22222222-2222-4222-8222-222222222222",
      "projectName": "Website refresh",
      "billable": true,
      "note": "Homepage revisions",
      "startedAt": "2026-09-10T16:00:00.000Z",
      "payRateCents": 5000,
      "currency": "USD",
      "status": "completed",
      "endedAt": "2026-09-10T17:30:00.000Z",
      "durationSeconds": 5400,
      "earnings": "75"
    }
  ],
  "nextCursor": null
}
```

A valid project UUID with no matching personal history returns an empty list. Invalid limit, ID, or cursor text returns `400 INVALID_REQUEST`; an undecodable payload returns `400 INVALID_CURSOR`. Read [pagination](https://www.tracktimer.app/docs/pagination) before requesting subsequent pages and [shared errors](https://www.tracktimer.app/docs/errors-and-retries) for other failures.

Examples use illustrative IDs and data. Use the values returned by your own workspace. [Review error handling and retry behavior.](https://www.tracktimer.app/docs/errors-and-retries)