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.

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:

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

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

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:

{
  "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:

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

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

Example Request

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.