Analytics API¶

The analytics API is served under /analytics/api/v1. The interactive OpenAPI reference is available at /analytics/docs on the host where Analytics is deployed.

Most endpoints require authentication. Browser users normally authenticate through Spiff Arena 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 Spiff Arena 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 "$SPIFFWORKS_BASE_URL/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 at /analytics/docs on your Analytics host.

Selecting the analytical store¶

PostgreSQL is the deployment default. Operators can set ANALYTICS_DATA_BACKEND=clickhouse for all analytical queries, or an authenticated diagnostic request can select a store with:

Spiff-Analytics-Data-Backend: postgres
Spiff-Analytics-Data-Backend: clickhouse

The equivalent query parameter is convenient for interactive API testing:

?data_backend=postgres
?data_backend=clickhouse

If a request supplies both selectors, they must name the same store. The status endpoint reports the request’s data_backend, the deployment’s default_data_backend, and available_data_backends. The Analytics UI provides a persistent Data source selector and sends the header on every warehouse query and export.

Both stores implement the query and export endpoints listed above. Model identifier discovery, authenticated static BPMN retrieval, authentication, frontend assets, and status responses retain their existing implementations because they are not analytical warehouse queries. The bin/check_dual_store_parity command sends one event set through normal ingestion and compares every endpoint currently queried by the UI, plus both export files.