# Candidate analytics

Time spent editing each candidate

Base URL: `https://api.cv-transformer.com/v1`. Endpoints: `GET /candidate_analytics`. Authenticate with the header `Authorization: Bearer YOUR_API_KEY` (see [authentication](https://www.cv-transformer.com/cs/api-reference/authentication.md)).

## The candidate analytic object

| Attribute | Type | Description |
| --- | --- | --- |
| `id` | `uuid` | Unique identifier. |
| `candidate_id` | `uuid \| null` | Identifier of the related candidate. References [`candidates.id`](https://www.cv-transformer.com/cs/api-reference/candidates.md). |
| `organization_id` | `uuid \| null` | Identifier of the related organization. References [`organizations.id`](https://www.cv-transformer.com/cs/api-reference/organizations.md). |
| `created_at` | `timestamp with time zone` | Creation timestamp. |
| `updated_at` | `timestamp with time zone` | Last modification timestamp. |
| `time_spent` | `real` | Time spent editing the candidate, in seconds. |

```json
{
  "id": "00000000-0000-0000-0000-000000000000",
  "candidate_id": "00000000-0000-0000-0000-000000000000",
  "organization_id": "00000000-0000-0000-0000-000000000000",
  "created_at": "2026-01-01T12:00:00+00:00",
  "updated_at": "2026-01-01T12:00:00+00:00",
  "time_spent": 0
}
```

### Related resources

Embed related resources with the [`select` parameter](https://www.cv-transformer.com/cs/api-reference/selecting.md), for example `select=*,candidates(*)`. Resources related through more than one column need the column as a hint, like `table!column(*)`.

| Embed | Type | Description |
| --- | --- | --- |
| `candidates(*)` | `object \| null` | The [candidate](https://www.cv-transformer.com/cs/api-reference/candidates.md) referenced by `candidate_id`. |
| `organizations(*)` | `object \| null` | The [organization](https://www.cv-transformer.com/cs/api-reference/organizations.md) referenced by `organization_id`. |

## List candidate analytics

`GET /v1/candidate_analytics` · requires the `candidates:read` scope

Filter on any attribute with `column=operator.value` (see [filtering](https://www.cv-transformer.com/cs/api-reference/filtering.md)). Choose columns and embed related resources with `select` (see [selecting](https://www.cv-transformer.com/cs/api-reference/selecting.md)), and sort and paginate with `order`, `limit` and `offset` (see [sorting and pagination](https://www.cv-transformer.com/cs/api-reference/sorting-pagination.md)).

```bash
curl "https://api.cv-transformer.com/v1/candidate_analytics?limit=10&select=*" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Responses:

- `200`: A list of candidate analytics with the selected columns. The `Content-Range` header holds the range returned and the total count, like `0-9/42`.
- `206`: Partial Content
- `400`: The request is malformed, for example an unknown column or an invalid filter.
- `401`: The API key is missing or invalid.
- `403`: The API key doesn't have the scope this request needs.
- `429`: The API key made more requests per minute than its rate limit allows. Retry after the number of seconds in the `Retry-After` header.

Errors have a JSON body with a `message`, `details` and `hint`, and for database errors a `code`. See the [introduction](https://www.cv-transformer.com/cs/api-reference.md) for more on errors. The full API is described by the OpenAPI spec at https://api.cv-transformer.com/v1/openapi.json.