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}/progress`	`POST`	Count distinct instances completing each activity across all lifecycle states, plus current waiting/errors at that activity.
`/analytics/api/v1/models/{identifier}/complete-progress`	`POST`	Count distinct finished instances completing each activity or recorded event.
`/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.

Progress rows contain workflow_spec, task_spec, completed, waiting, and errors. They use the same instance-start-date and metadata filters as Overview, without selecting only completed instances. completed requires task state COMPLETED; retries/loops count once per instance and activity. waiting requires an active instance and unfinished task; errors requires an errored instance and task state ERROR. These counts can overlap in looping processes; they are not a partition and do not measure permanent abandonment.

Duration distribution rows include sample_count (observations per bucket). Percentiles are approximate; calculate positions using cumulative sample counts, not equal bucket weights.

For active instances, /tasks and /{task_spec} return only unfinished tasks (time since the task started); tasks an active instance already finished are excluded. /tasks still returns reached milestones for active instances. Finished and errored instances return all their tasks. /{task_spec} accepts an optional workflow_spec query parameter to scope a task id to one workflow (task ids can repeat across subprocesses); omitting it keeps the unscoped behavior.

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¶

Which analytical store backs these endpoints is a deployment setting managed by your SpiffWorks administrator. If you need to confirm which store your environment uses, ask your admin.