> ## Documentation Index
> Fetch the complete documentation index at: https://docs.autosana.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage API

> Read flow run and AI action usage for a workspace

These endpoints return how many flow runs and AI actions a workspace used in any time range, so you can track usage or bill it on to your own customers.

All requests require an API key in the `X-API-Key` header. See [API Reference](/api-reference) for authentication and the standard `401` / `403` / `429` / `500` error shapes shared by every endpoint on this page.

<Note>
  **An API key reads its own workspace.** To cover several workspaces, call these endpoints once with each workspace's key.
</Note>

<Note>
  A run counts toward the range it was created in, together with all of its actions. **[Billing & usage](https://autosana.ai/settings?tab=billing)** counts each action when it happens, so the two can differ slightly for runs in progress at either end of a range.
</Note>

***

## Get Usage Totals

Returns the totals for every flow run your workspace created in the range.

<Note>
  **GET** `/api/v1/usage` — Returns `200 OK`
</Note>

### Query Parameters

<ParamField query="start" type="string" required>
  Start of the range, inclusive. An ISO 8601 date or timestamp, read as UTC when it has no offset.
</ParamField>

<ParamField query="end" type="string" required>
  End of the range, exclusive. Must be after `start`.
</ParamField>

### Example Request

```bash theme={null}
curl -X GET "https://backend.autosana.ai/api/v1/usage?start=2026-10-01&end=2026-11-01" \
  -H "X-API-Key: YOUR_API_KEY"
```

### Response Fields

<ResponseField name="start" type="string">
  Start of the range, as an ISO 8601 UTC timestamp.
</ResponseField>

<ResponseField name="end" type="string">
  End of the range, as an ISO 8601 UTC timestamp.
</ResponseField>

<ResponseField name="run_count" type="integer">
  Flow runs created in the range.
</ResponseField>

<ResponseField name="duration_seconds" type="number">
  Total run time of the finished runs, in seconds.
</ResponseField>

<ResponseField name="action_count" type="integer">
  AI actions taken by those runs: `uncached_action_count` plus `cached_action_count`.
</ResponseField>

<ResponseField name="uncached_action_count" type="integer">
  AI actions that were not replayed from cache.
</ResponseField>

<ResponseField name="cached_action_count" type="integer">
  AI actions replayed from cache. These cost 10% of an uncached action. See [Run Caching](/flows#run-caching).
</ResponseField>

#### Example Response

```json theme={null}
{
  "start": "2026-10-01T00:00:00Z",
  "end": "2026-11-01T00:00:00Z",
  "run_count": 412,
  "duration_seconds": 51234.8,
  "action_count": 6180,
  "uncached_action_count": 1240,
  "cached_action_count": 4940
}
```

### Errors

| Status | Description |
| - | - |
| 400 | `end` is not after `start` |
| 422 | `start` or `end` is missing or not a date or timestamp |

***

## List Run Usage

Returns the runs behind the totals, oldest first, each with its own usage and a link to the run in the dashboard.

<Note>
  **GET** `/api/v1/usage/runs` — Returns `200 OK`
</Note>

### Query Parameters

<ParamField query="start" type="string" required>
  Start of the range, inclusive. An ISO 8601 date or timestamp, read as UTC when it has no offset.
</ParamField>

<ParamField query="end" type="string" required>
  End of the range, exclusive. Must be after `start`.
</ParamField>

<ParamField query="limit" type="integer" default="100">
  Runs per page, from 1 to 500.
</ParamField>

<ParamField query="starting_after" type="string">
  The `run_id` of the last run on the previous page. Returns the runs listed after it. Keep `start` and `end` the same while paging: a run outside the range still marks a position, so you get the runs in the range created after it.
</ParamField>

### Example Request

```bash theme={null}
curl -X GET "https://backend.autosana.ai/api/v1/usage/runs?start=2026-10-01&end=2026-11-01&limit=100" \
  -H "X-API-Key: YOUR_API_KEY"
```

### Response Fields

<ResponseField name="runs" type="array">
  One page of runs.

  <Expandable title="Run object">
    <ResponseField name="run_id" type="string">
      Unique identifier (UUID). Pass it to [Get Run Results](/api-runs#get-run-results) for the run's full details.
    </ResponseField>

    <ResponseField name="flow_id" type="string | null">
      The flow that ran.
    </ResponseField>

    <ResponseField name="flow_name" type="string | null">
      The flow's name.
    </ResponseField>

    <ResponseField name="status" type="string | null">
      Run status, such as `passed`, `failed` or `error`. See [Run Status](/api-runs#run-status) for the values.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      When the run was created. This places the run in a range.
    </ResponseField>

    <ResponseField name="started_at" type="string | null">
      When the run started executing.
    </ResponseField>

    <ResponseField name="completed_at" type="string | null">
      When the run finished.
    </ResponseField>

    <ResponseField name="duration_seconds" type="number | null">
      Seconds from `started_at` to `completed_at`. `null` until the run finishes, or when it never started.
    </ResponseField>

    <ResponseField name="action_count" type="integer">
      AI actions the run took: `uncached_action_count` plus `cached_action_count`.
    </ResponseField>

    <ResponseField name="uncached_action_count" type="integer">
      AI actions that were not replayed from cache.
    </ResponseField>

    <ResponseField name="cached_action_count" type="integer">
      AI actions replayed from cache.
    </ResponseField>

    <ResponseField name="url" type="string">
      Link to the run in the dashboard.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="has_more" type="boolean">
  Whether more runs follow this page. If `true`, request the next page with `starting_after` set to the last `run_id` in `runs`.
</ResponseField>

#### Example Response

```json theme={null}
{
  "runs": [
    {
      "run_id": "660e8400-e29b-41d4-a716-446655440001",
      "flow_id": "550e8400-e29b-41d4-a716-446655440000",
      "flow_name": "Log in",
      "status": "passed",
      "created_at": "2026-10-02T08:00:01.123456Z",
      "started_at": "2026-10-02T08:01:00Z",
      "completed_at": "2026-10-02T08:05:11.400000Z",
      "duration_seconds": 251.4,
      "action_count": 25,
      "uncached_action_count": 5,
      "cached_action_count": 20,
      "url": "https://autosana.ai/runs/flow/660e8400-e29b-41d4-a716-446655440001"
    }
  ],
  "has_more": true
}
```

### Errors

| Status | Description |
| - | - |
| 400 | `end` is not after `start`, or `starting_after` is not a run in this workspace |
| 422 | `start` or `end` is missing or not a date or timestamp, `limit` is outside 1 to 500, or `starting_after` is not a UUID |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.