# Summarize what usage cost the organization

Source: <https://everruns.com/docs/api/operations/get_cost_summary/>

[Docs](https://everruns.com/docs/)/[API reference](https://everruns.com/docs/api/)/[Operations & billing](https://everruns.com/docs/api/groups/operations-billing/)/Summarize what usage cost the organization

# Summarize what usage cost the organization

Preview

Operate durable execution, schedules, sandbox infrastructure, budgets, payments and audit logs.

Public APIEverruns Cloud and self-hosted Platform

GET`/v1/costs/summary`

See [authentication](https://everruns.com/docs/sre/runbooks/authentication/) for credentials and permissions.

## Parameters

### Query Parameters

**from**

string format: date-time

Window start (inclusive). Default: the start of this month.

**to**

string format: date-time

Window end (exclusive). Default: now.

**agent_id**

string

Only this agent (`agent_...`).

## Responses

200Success

### 200

Success

Media typeapplication/json

Org cost over a window, grouped several ways.

object

**by_agent**

required

Totals by agent.

Array\<object>

One line of the costs summary.

object

**basis**

required

Where the amounts came from: host, rate, provider, list_price, unpriced, or mixed.

string

**cost_usd**

required

Priced cost in USD. Unpriced usage is not in it.

number format: double

**key**

Group key: an agent id, a user id, a source key, a basis, a day.

string | null

**label**

Display name for the key, such as the agent’s name.

string | null

**quantity**

required

Tokens for models, hours for sandboxes, summed as recorded.

number format: double

**records**

required

Usage records in the group, priced or not.

integer format: int64

**unpriced_records**

required

Usage records with no price.

integer format: int64

**by_basis**

required

Totals by where the amount came from.

Array\<object>

One line of the costs summary.

object

**basis**

required

Where the amounts came from: host, rate, provider, list_price, unpriced, or mixed.

string

**cost_usd**

required

Priced cost in USD. Unpriced usage is not in it.

number format: double

**key**

Group key: an agent id, a user id, a source key, a basis, a day.

string | null

**label**

Display name for the key, such as the agent’s name.

string | null

**quantity**

required

Tokens for models, hours for sandboxes, summed as recorded.

number format: double

**records**

required

Usage records in the group, priced or not.

integer format: int64

**unpriced_records**

required

Usage records with no price.

integer format: int64

**by_day**

required

Totals by day, in the org’s timezone.

Array\<object>

One line of the costs summary.

object

**basis**

required

Where the amounts came from: host, rate, provider, list_price, unpriced, or mixed.

string

**cost_usd**

required

Priced cost in USD. Unpriced usage is not in it.

number format: double

**key**

Group key: an agent id, a user id, a source key, a basis, a day.

string | null

**label**

Display name for the key, such as the agent’s name.

string | null

**quantity**

required

Tokens for models, hours for sandboxes, summed as recorded.

number format: double

**records**

required

Usage records in the group, priced or not.

integer format: int64

**unpriced_records**

required

Usage records with no price.

integer format: int64

**by_source**

required

Totals by what was used, such as a provider and model.

Array\<object>

One line of the costs summary.

object

**basis**

required

Where the amounts came from: host, rate, provider, list_price, unpriced, or mixed.

string

**cost_usd**

required

Priced cost in USD. Unpriced usage is not in it.

number format: double

**key**

Group key: an agent id, a user id, a source key, a basis, a day.

string | null

**label**

Display name for the key, such as the agent’s name.

string | null

**quantity**

required

Tokens for models, hours for sandboxes, summed as recorded.

number format: double

**records**

required

Usage records in the group, priced or not.

integer format: int64

**unpriced_records**

required

Usage records with no price.

integer format: int64

**by_started_by**

required

Totals by who started the work: `person`, or `unattended` (schedules and other runs nobody watches).

Array\<object>

One line of the costs summary.

object

**basis**

required

Where the amounts came from: host, rate, provider, list_price, unpriced, or mixed.

string

**cost_usd**

required

Priced cost in USD. Unpriced usage is not in it.

number format: double

**key**

Group key: an agent id, a user id, a source key, a basis, a day.

string | null

**label**

Display name for the key, such as the agent’s name.

string | null

**quantity**

required

Tokens for models, hours for sandboxes, summed as recorded.

number format: double

**records**

required

Usage records in the group, priced or not.

integer format: int64

**unpriced_records**

required

Usage records with no price.

integer format: int64

**by_user**

required

Totals by the person the usage counts for.

Array\<object>

One line of the costs summary.

object

**basis**

required

Where the amounts came from: host, rate, provider, list_price, unpriced, or mixed.

string

**cost_usd**

required

Priced cost in USD. Unpriced usage is not in it.

number format: double

**key**

Group key: an agent id, a user id, a source key, a basis, a day.

string | null

**label**

Display name for the key, such as the agent’s name.

string | null

**quantity**

required

Tokens for models, hours for sandboxes, summed as recorded.

number format: double

**records**

required

Usage records in the group, priced or not.

integer format: int64

**unpriced_records**

required

Usage records with no price.

integer format: int64

**cost_usd**

required

Priced cost in USD over the window. Unpriced usage is not in it.

number format: double

**from**

required

Window start (inclusive).

string format: date-time

**runs_with_agents**

required

Runs where an agent handed work to other agents: their whole cost by the agent the run started with, split by the agent that spent it. Every amount is also in `by_agent`, under the agent that spent it.

Array\<object>

The runs one agent led, with whole-run cost and who spent it.

object

**agent_id**

required

The agent the runs started with.

string

**agent_name**

required

string

**by_agent**

required

Who spent it, the leading agent itself included, largest first.

Array\<object>

One agent’s spend within the runs another agent led.

object

**agent_id**

Absent for usage recorded with no agent.

string | null

**agent_name**

string | null

**cost_usd**

required

number format: double

**relation**

required

`lead` for the leading agent itself, `created_here` for an agent created as part of it, `linked` for any other agent.

string

**cost_usd**

required

Priced cost of those runs in USD, every agent included.

number format: double

**runs**

required

Runs it handed work to other agents in, with usage in the window.

integer format: int64

**timezone**

required

The org’s timezone; calendar windows and days use it.

string

**to**

required

Window end (exclusive).

string format: date-time

**unpriced_records**

required

Usage records over the window with no price.

integer format: int64

### Example

```json
{
  "runs_with_agents": [
    {
      "agent_id": "agent_01h9xk1a",
      "agent_name": "Foreman",
      "by_agent": [
        {
          "agent_id": "agent_01h9xk2m",
          "agent_name": "Implement",
          "cost_usd": 121.3,
          "relation": "created_here"
        }
      ],
      "cost_usd": 212.4,
      "runs": 12
    }
  ]
}
```

FetchcURL

Request

```js
const url = 'https://app.everruns.com/api/v1/costs/summary';
const options = {method: 'GET'};


try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

Request

```sh
curl --request GET \
  --url https://app.everruns.com/api/v1/costs/summary
```

Additional language examples require JavaScript. The default request example is available above.

200

200 · Success

```json
{
  "by_agent": [
    {
      "basis": "string",
      "cost_usd": 0,
      "quantity": 0,
      "records": 0,
      "unpriced_records": 0
    }
  ],
  "by_basis": [
    {
      "basis": "string",
      "cost_usd": 0,
      "quantity": 0,
      "records": 0,
      "unpriced_records": 0
    }
  ],
  "by_day": [
    {
      "basis": "string",
      "cost_usd": 0,
      "quantity": 0,
      "records": 0,
      "unpriced_records": 0
    }
  ],
  "by_source": [
    {
      "basis": "string",
      "cost_usd": 0,
      "quantity": 0,
      "records": 0,
      "unpriced_records": 0
    }
  ],
  "by_started_by": [
    {
      "basis": "string",
      "cost_usd": 0,
      "quantity": 0,
      "records": 0,
      "unpriced_records": 0
    }
  ],
  "by_user": [
    {
      "basis": "string",
      "cost_usd": 0,
      "quantity": 0,
      "records": 0,
      "unpriced_records": 0
    }
  ],
  "cost_usd": 0,
  "from": "2026-10-12T09:00:00Z",
  "runs_with_agents": [
    {
      "agent_id": "agent_01h9xk1a",
      "agent_name": "Foreman",
      "by_agent": [],
      "cost_usd": 212.4,
      "runs": 12
    }
  ],
  "timezone": "string",
  "to": "2026-10-12T09:00:00Z",
  "unpriced_records": 0
}
```

## Matching endpoints