Usage API

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 for authentication and the standard 401 / 403 / 429 / 500 error shapes shared by every endpoint on this page.

An API key reads its own workspace. To cover several workspaces, call these endpoints once with each workspace’s key.

A run counts toward the range it was created in, together with all of its actions. Billing & usage counts each action when it happens, so the two can differ slightly for runs in progress at either end of a range.

Get Usage Totals

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

GET /api/v1/usage — Returns 200 OK

Query Parameters

string

required

Start of the range, inclusive. An ISO 8601 date or timestamp, read as UTC when it has no offset.

string

required

End of the range, exclusive. Must be after start.

Example Request

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

string

Start of the range, as an ISO 8601 UTC timestamp.

string

End of the range, as an ISO 8601 UTC timestamp.

integer

Flow runs created in the range.

number

Total run time of the finished runs, in seconds.

integer

AI actions taken by those runs: uncached_action_count plus cached_action_count.

integer

AI actions that were not replayed from cache.

integer

AI actions replayed from cache. These cost 10% of an uncached action. See Run Caching.

Example Response

{
  "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.

GET /api/v1/usage/runs — Returns 200 OK

Query Parameters

string

required

Start of the range, inclusive. An ISO 8601 date or timestamp, read as UTC when it has no offset.

string

required

End of the range, exclusive. Must be after start.

integer

default:"100"

Runs per page, from 1 to 500.

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.

Example Request

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

array

One page of runs.

Show Run object

string

Unique identifier (UUID). Pass it to Get Run Results for the run’s full details.

string | null

The flow that ran.

string | null

The flow’s name.

string | null

Run status, such as passed, failed or error. See Run Status for the values.

string

When the run was created. This places the run in a range.

string | null

When the run started executing.

string | null

When the run finished.

number | null

Seconds from started_at to completed_at. null until the run finishes, or when it never started.

integer

AI actions the run took: uncached_action_count plus cached_action_count.

integer

AI actions that were not replayed from cache.

integer

AI actions replayed from cache.

string

Link to the run in the dashboard.

boolean

Whether more runs follow this page. If true, request the next page with starting_after set to the last run_id in runs.

Example Response

{
  "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

Getting Started

Core Features

Best Practices

Code-Managed Flows

Guides

Integrations

Uploading Your App

APIs

Get Usage Totals

Query Parameters

Example Request

Response Fields

Example Response

Errors

List Run Usage

Query Parameters

Example Request

Response Fields

Example Response

Errors

​Get Usage Totals

​Query Parameters

​Example Request

​Response Fields

​Example Response

​Errors

​List Run Usage

​Query Parameters

​Example Request

​Response Fields

​Example Response

​Errors

Get Usage Totals

Query Parameters

Example Request

Response Fields

Example Response

Errors

List Run Usage

Query Parameters

Example Request

Response Fields

Example Response

Errors