Get Status History

Time	Status	User Agent
Retrieving recent requests…

When to Use This Endpoint

Use case	Description
Audit & compliance	Get a timestamped record of every state the task passed through — useful for dispute resolution, refund justification, or internal reporting.
Debugging a failed task	Understand exactly which step the AI agent was on when it failed, and how many times it was retried.
Credit reconciliation	See how many credits were consumed per execution attempt and per step, so you can reconcile usage against your CartAI account.
Support escalation	Share the full history with CartAI support to help diagnose issues with a specific task.
Analytics & monitoring	Track how long tasks spend in each status, identify slow merchants, or spot patterns in failures.

How It Differs from Get Checkout Task

Both GET /checkout/{taskId} and GET /checkout/{taskId}/status-history are read operations on the same task, but they serve different purposes:

	`GET /checkout/{taskId}`	`GET /checkout/{taskId}/status-history`
Primary purpose	Current state snapshot	Full chronological audit trail
Data returned	Status, `derivedDetails`, customer, tasks, iterations	All status transitions with timestamps and credits per step
Best for	Polling live task progress	Post-execution analysis, debugging, credit reconciliation
Granularity	Task-level	Step-level within each execution attempt
Credits info	Overall total	Yes — per step and per execution

Use GET /checkout/{taskId} when you want to know what is happening now. Use GET /checkout/{taskId}/status-history when you want to know everything that happened and when.

Authentication

Every request must include your API key in the request header.

x-api-key: YOUR_API_KEY_HERE

Store your API key in a backend environment variable or secrets manager — never expose it in client-side code.

Path Parameters

Parameter	Type	Required	Description
`taskId`	string (UUID)	✅ Yes	The `taskId` returned when the checkout task was originally created via `POST /checkout`. Example: `019bd5c5-2824-76d1-aa7a-01db5c4d7065`

Response Schema

Envelope fields

The response is wrapped in a standard envelope object.

Field	Type	Description
`status`	string	API-level result indicator. `"SUCCESS"` means the request was processed correctly — this does not reflect the outcome of the checkout task itself.
`message`	string	Human-readable description of the API result. Example: `"History retrieved successfully"`.
`data`	array of objects	Flat, ordered list of step records for this task. Most recent step first (descending order by `createdAt`). Each item represents one recorded step in the agent's execution. See `data[]` below.

`data[]` — step record fields

Each object in the data array represents a single step the AI agent recorded during execution. Steps are returned in reverse chronological order — the most recent step is first.

Field	Type	Description
`id`	integer	Auto-incremented internal record ID. Higher `id` values = more recent steps. Use this to sort ascending for chronological reading.
`taskId`	string (UUID)	The task this step belongs to. Always matches the `taskId` in your request path.
`executionId`	string (UUID)	The execution attempt this step belongs to. Steps from the same attempt share the same `executionId`. Cross-reference this with `GET /checkout/{taskId}` or webhook payloads to correlate steps with a specific attempt.
`status`	string	The agent-facing step label — a granular description of what the AI agent was doing at this point (e.g. `CREDIT_CARD_INPUT`, `ORDER_CONFIRMED`, `SHIPPING_SELECTED`). More specific than `systemStatus`. See `status` vs `systemStatus`.
`systemStatus`	string	The system-level lifecycle status at the time of this step — the same coarser-grained values emitted via webhooks (e.g. `IN_PROGRESS`, `FAILED`, `COMPLETED`).
`createdAt`	string (datetime)	When this step was recorded. Format: `YYYY-MM-DD HH:MM:SS.ffffff` (microsecond precision).
`isFailed`	boolean	Whether this specific step was a failure point. A step can have `isFailed: true` even if the overall task eventually succeeded (e.g. a transient error the agent recovered from).
`note`	string \| null	Optional human-readable note attached to this step by the CartAI system. Provides context when `isFailed` is `true`. `null` when no additional information is available.
`creditsConsumed`	number	Credits consumed during this step. A decimal value (e.g. `0.79`, `0.38`). Steps involving active agent work consume more credits than transitional steps.
`retryCount`	integer	Which retry attempt this step belongs to. `1` = first attempt, `2` = first retry, and so on. Steps sharing the same `executionId` will share the same `retryCount`.

`status` vs `systemStatus`

These two fields capture the same moment at different levels of granularity.

Field	Granularity	Who uses it	Example values
`status`	Fine-grained — the specific action the agent was performing	Debugging, support escalation	`CREDIT_CARD_INPUT`, `ORDER_CONFIRMED`, `SHIPPING_SELECTED`, `CART_ADD`, `LOGIN_ATTEMPT`
`systemStatus`	Coarse-grained — the lifecycle phase	Webhook integration, UI status display	`IN_PROGRESS`, `FAILED`, `COMPLETED`, `PENDING_CONFIRMATION`, `CANCELLED`

Think of systemStatus as the chapter, and status as the sentence within it. Multiple consecutive steps can share the same systemStatus (e.g. IN_PROGRESS) while their status values change as the agent moves through individual actions.

Full Response Example

A task with two recorded steps from the same execution attempt — the agent entered credit card details (CREDIT_CARD_INPUT) and then an order confirmation was recorded (ORDER_CONFIRMED). Results are most-recent-first:

{
    "status": "SUCCESS",
    "data": [
        {
            "id": 19772,
            "taskId": "019e4a66-f86f-7eb0-ad9f-2aa1f149c03c",
            "executionId": "019e4a66-f86f-7eb0-ad9f-2a9bc9e5a367",
            "status": "ORDER_CONFIRMED",
            "systemStatus": "FAILED",
            "createdAt": "2026-05-21 12:04:53.639675",
            "isFailed": false,
            "note": null,
            "creditsConsumed": 0.79,
            "retryCount": 1
        },
        {
            "id": 19771,
            "taskId": "019e4a66-f86f-7eb0-ad9f-2aa1f149c03c",
            "executionId": "019e4a66-f86f-7eb0-ad9f-2a9bc9e5a367",
            "status": "CREDIT_CARD_INPUT",
            "systemStatus": "IN_PROGRESS",
            "createdAt": "2026-05-21 12:03:39.117765",
            "isFailed": false,
            "note": null,
            "creditsConsumed": 0.38,
            "retryCount": 1
        },
        {
            "id": 19769,
            "taskId": "019e4a66-f86f-7eb0-ad9f-2aa1f149c03c",
            "executionId": "019e4a66-f86f-7eb0-ad9f-2a9bc9e5a367",
            "status": "SHIPMENT_AND_TAX_RETRIVAL",
            "systemStatus": "IN_PROGRESS",
            "createdAt": "2026-05-21 12:02:05.368215",
            "isFailed": false,
            "note": null,
            "creditsConsumed": 0.34,
            "retryCount": 1
        },
        {
            "id": 19768,
            "taskId": "019e4a66-f86f-7eb0-ad9f-2aa1f149c03c",
            "executionId": "019e4a66-f86f-7eb0-ad9f-2a9bc9e5a367",
            "status": "ADDRESS_FILLING",
            "systemStatus": "IN_PROGRESS",
            "createdAt": "2026-05-21 12:01:40.427530",
            "isFailed": false,
            "note": null,
            "creditsConsumed": 0.0,
            "retryCount": 1
        },
        {
            "id": 19767,
            "taskId": "019e4a66-f86f-7eb0-ad9f-2aa1f149c03c",
            "executionId": "019e4a66-f86f-7eb0-ad9f-2a9bc9e5a367",
            "status": "GUEST_CHECKOUT",
            "systemStatus": "IN_PROGRESS",
            "createdAt": "2026-05-21 12:01:30.505375",
            "isFailed": false,
            "note": null,
            "creditsConsumed": 0.75,
            "retryCount": 1
        },
        {
            "id": 19765,
            "taskId": "019e4a66-f86f-7eb0-ad9f-2aa1f149c03c",
            "executionId": "019e4a66-f86f-7eb0-ad9f-2a9bc9e5a367",
            "status": "CART_VERIFICATION",
            "systemStatus": "IN_PROGRESS",
            "createdAt": "2026-05-21 12:00:26.913072",
            "isFailed": false,
            "note": null,
            "creditsConsumed": 0.24,
            "retryCount": 1
        },
        {
            "id": 19764,
            "taskId": "019e4a66-f86f-7eb0-ad9f-2aa1f149c03c",
            "executionId": "019e4a66-f86f-7eb0-ad9f-2a9bc9e5a367",
            "status": "ADD_TO_CART",
            "systemStatus": "IN_PROGRESS",
            "createdAt": "2026-05-21 12:00:07.155100",
            "isFailed": false,
            "note": null,
            "creditsConsumed": 0.46,
            "retryCount": 1
        },
        {
            "id": 19763,
            "taskId": "019e4a66-f86f-7eb0-ad9f-2aa1f149c03c",
            "executionId": "019e4a66-f86f-7eb0-ad9f-2a9bc9e5a367",
            "status": "PAGE_NAVIGATION",
            "systemStatus": "IN_PROGRESS",
            "createdAt": "2026-05-21 11:59:31.175712",
            "isFailed": false,
            "note": null,
            "creditsConsumed": 0.32,
            "retryCount": 1
        },
        {
            "id": 19760,
            "taskId": "019e4a66-f86f-7eb0-ad9f-2aa1f149c03c",
            "executionId": "019e4a66-f86f-7eb0-ad9f-2a9bc9e5a367",
            "status": "STARTED",
            "systemStatus": "STARTED",
            "createdAt": "2026-05-21 11:58:54.050595",
            "isFailed": false,
            "note": null,
            "creditsConsumed": 0.0,
            "retryCount": 1
        },
        {
            "id": 19758,
            "taskId": "019e4a66-f86f-7eb0-ad9f-2aa1f149c03c",
            "executionId": "019e4a66-f86f-7eb0-ad9f-2a9bc9e5a367",
            "status": "QUEUED",
            "systemStatus": "QUEUED",
            "createdAt": "2026-05-21 11:58:42.814429",
            "isFailed": false,
            "note": null,
            "creditsConsumed": 0.0,
            "retryCount": 1
        }
    ],
    "message": "History retrieved successfully"
}

Reading this response:

The array is most-recent-first. Step id: 19772 (ORDER_CONFIRMED, at 12:04:53) happened after id: 19771 (CREDIT_CARD_INPUT, at 12:03:39). To read chronologically, reverse the array or sort ascending by id.
Both steps share executionId: "019e4a66-...a367" and retryCount: 1 — they belong to the same single execution attempt.
Step id: 19772 carries systemStatus: "FAILED" but isFailed: false — the system entered a failed state at this point in the lifecycle, but this specific step's action (ORDER_CONFIRMED) did not itself trigger the failure. The root cause may have occurred at the system level after this step.
Total credits for this task so far: 0.38 + 0.79 = 1.17.