Sign in

v51

latestOpenAPI 3.0.0raw.githubusercontent.com2026-08-014102371.0 MB
Timeline

Trigger an AI analysis of an ended activeflow.

Analyzes a completed (ended) activeflow asynchronously, producing a structured verdict. Returns the progressing record on a fresh trigger, or the existing record when one is already present (idempotent unless reanalyze is set). Requires CustomerAdmin or CustomerManager permission. The analysis is scoped to the authenticated customer; the activeflow must belong to that customer and must be in the ended state.

post/timeline-analyses

Request body

activeflow_idstring uuid required

The ID of the ended activeflow to analyze. Returned from the GET /activeflows response.

reanalyzeboolean

When true, discards the existing completed/failed verdict and runs a fresh analysis (subject to a short cooldown). When false or omitted, an existing record is returned unchanged.

Example request

{
  "activeflow_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
}

Response

The progressing or existing analysis record.

idstring uuid

The unique identifier of the analysis. Returned from the POST /timeline-analyses or GET /timeline-analyses response.

customer_idstring uuid

The customer who owns this analysis.

activeflow_idstring uuid

The ended activeflow that was analyzed. Returned from the GET /activeflows response.

status'progressing' | 'completed' | 'failed'

Lifecycle state of the analysis.

resultobject

The structured analysis verdict. Null while progressing or on failure. Present on successful completion. Includes an overall status, a narrative, detected issues with evidence pointers, and per-type resource usage.

errorstring

Sanitized failure reason when status is failed.

tm_createstring date-time

Timestamp when the analysis was created.

tm_updatestring date-time nullable

Timestamp when the analysis was last updated.

Example response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "customer_id": "7c4d2f3a-1b8e-4f5c-9a6d-3e2f1a0b4c5d",
  "activeflow_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "status": "completed",
  "result": {
    "version": 1,
    "overall_status": "warning",
    "input_reduced": false,
    "narrative": "The call connected, the IVR collected the customer's intent, and the call was routed to an available agent who resolved the request.",
    "issues": [
      {
        "severity": "warning",
        "area": "routing",
        "summary": "The queue wait exceeded the configured target by 8 seconds.",
        "evidence": [
          {
            "evidence_index": 12,
            "event_type": "queue_joined",
            "timestamp": "2026-01-15T09:30:12.000000Z",
            "resource_id": "5e3f8b2a-9c1d-4e6f-8a7b-2d3c4e5f6a7b"
          }
        ]
      }
    ],
    "resources_used": [
      {
        "type": "call",
        "count": 1
      },
      {
        "type": "queuecall",
        "count": 1
      }
    ]
  },
  "error": "analysis engine timed out",
  "tm_create": "2026-01-15T09:30:00.000000Z",
  "tm_update": "2026-01-15T09:30:05.000000Z"
}