# Analytics API

The analytics API is served under `/analytics/api/v1`.
The public interactive OpenAPI reference is available at [https://emerson.spiff.works/analytics/docs](https://emerson.spiff.works/analytics/docs).

Most endpoints require authentication.
Browser users normally authenticate through SpiffArena and then call the API with session cookies.
API clients can authenticate with either:

- an `Authorization: Bearer <token>` header plus `SpiffWorkflow-Authentication-Identifier`, or
- a `SpiffWorkflow-Api-Key` header when API key access is configured.

## Identifiers

Most endpoints include an `identifier` path value.
Identifiers refer to a process group or process model.

When a SpiffArena identifier contains `/`, replace it with `:` in the API path.
For example:

```text
Process group/model identifier: finance/invoice-review
API path identifier: finance:invoice-review
```

For group-level queries, append `%` to include descendants:

```text
finance%
```

Use `GET /analytics/api/v1/identifiers/list` to discover available process groups and models.

## Request Body

POST query endpoints accept the same JSON body shape:

```json
{
  "start": "2026-05-01T00:00:00Z",
  "end": "2026-05-27T23:59:59Z",
  "metadata": [
    {
      "name": "region",
      "type": "text",
      "value": "Northeast"
    }
  ]
}
```

Fields:

- `start`: beginning of the reporting window.
- `end`: end of the reporting window.
- `metadata`: optional filters against process metadata values.
- `metadata[].name`: metadata key.
- `metadata[].type`: one of `text`, `int`, or `float`.
- `metadata[].value`: value to match.

## Core Endpoints

| Endpoint | Method | Use |
| --- | --- | --- |
| `/analytics/api/v1/identifiers/list` | `GET` | List process groups and process models available to analytics. |
| `/analytics/api/v1/overview/{identifier}` | `POST` | Get active, completed, and errored counts and summary duration data. |
| `/analytics/api/v1/trends/{identifier}` | `POST` | Get activity trends over time. |
| `/analytics/api/v1/instances/{identifier}` | `POST` | Get process instance rows for the selected filters. |
| `/analytics/api/v1/tasks/{identifier}` | `POST` | Get task rows for the selected filters. |
| `/analytics/api/v1/milestones/{identifier}` | `POST` | Get milestone rows for the selected filters. |
| `/analytics/api/v1/export/{identifier}` | `POST` | Download a zip export containing `instances.csv` and `tasks.csv`. |

## Model Detail Endpoints

Use these endpoints when the identifier represents a single process model.

| Endpoint | Method | Use |
| --- | --- | --- |
| `/analytics/api/v1/models/{identifier}/tasks` | `POST` | Summarize task counts and durations for a model. |
| `/analytics/api/v1/models/{identifier}/duration` | `POST` | Get model duration percentile data. |
| `/analytics/api/v1/models/{identifier}/milestones` | `POST` | Get milestone duration distribution data. |
| `/analytics/api/v1/models/{identifier}/{task_spec}` | `POST` | Get duration distribution data for a specific BPMN task id. |

## Error Endpoints

| Endpoint | Method | Use |
| --- | --- | --- |
| `/analytics/api/v1/errors/{identifier}/summary` | `POST` | Summarize errors by model. |
| `/analytics/api/v1/errors/{identifier}/detail` | `POST` | Get task-level error detail for a model. |

## Static BPMN Files

The UI uses:

```text
GET /analytics/api/v1/static/{file_path}
```

to retrieve BPMN files for diagram display.
This endpoint is primarily for the analytics UI.

## Example Request

```shell
curl https://emerson.spiff.works/analytics/api/v1/overview/finance:invoice-review \
  -H "Authorization: Bearer $TOKEN" \
  -H "SpiffWorkflow-Authentication-Identifier: default" \
  -H "Content-Type: application/json" \
  --data '{
    "start": "2026-05-01T00:00:00Z",
    "end": "2026-05-27T23:59:59Z",
    "metadata": []
  }'
```

For live schema details, response examples, and validation errors, use the [interactive API reference](https://emerson.spiff.works/analytics/docs).