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

# Cost API

> Token spend attribution by agent, team, model, and time series

## Cost Summary

```
GET /cost/summary
```

Get aggregate cost data for your tenant.

| Parameter | Type   | Default        | Description            |
| --------- | ------ | -------------- | ---------------------- |
| `period`  | string | `month`        | `day`, `week`, `month` |
| `from`    | string | Start of month | ISO 8601 date          |
| `to`      | string | Today          | ISO 8601 date          |

```bash theme={null}
curl "https://api.meshai.dev/api/v1/cost/summary?period=month&from=2026-03-01" \
  -H "Authorization: Bearer msh_YOUR_API_KEY"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "total_cost_usd": 1245.67,
      "total_input_tokens": 15234000,
      "total_output_tokens": 4567000,
      "total_requests": 8923,
      "period": "month",
      "from": "2026-03-01T00:00:00Z",
      "to": "2026-03-17T23:59:59Z"
    }
  }
  ```
</ResponseExample>

## Cost by Agent

```
GET /cost/by-agent
```

Break down costs per agent, sorted by cost descending.

```bash theme={null}
curl "https://api.meshai.dev/api/v1/cost/by-agent?from=2026-03-01&limit=10" \
  -H "Authorization: Bearer msh_YOUR_API_KEY"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": [
      {
        "agent_id": "agt_abc123",
        "agent_name": "production-summarizer",
        "team": "support-team",
        "total_cost_usd": 456.78,
        "input_tokens": 5600000,
        "output_tokens": 1200000,
        "requests": 3400
      }
    ],
    "meta": { "total": 12, "page": 1, "limit": 10 }
  }
  ```
</ResponseExample>

## Cost by Team

```
GET /cost/by-team
```

Break down costs per team.

```bash theme={null}
curl "https://api.meshai.dev/api/v1/cost/by-team?from=2026-03-01" \
  -H "Authorization: Bearer msh_YOUR_API_KEY"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": [
      {
        "team": "support-team",
        "total_cost_usd": 645.23,
        "input_tokens": 7800000,
        "output_tokens": 2100000,
        "requests": 4500,
        "agent_count": 5
      },
      {
        "team": "sales-team",
        "total_cost_usd": 412.30,
        "input_tokens": 5200000,
        "output_tokens": 1500000,
        "requests": 2800,
        "agent_count": 3
      }
    ]
  }
  ```
</ResponseExample>

## Cost by Model

```
GET /cost/by-model
```

Break down costs per model.

```bash theme={null}
curl "https://api.meshai.dev/api/v1/cost/by-model?from=2026-03-01" \
  -H "Authorization: Bearer msh_YOUR_API_KEY"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": [
      {
        "model_provider": "openai",
        "model_name": "gpt-4o",
        "total_cost_usd": 890.12,
        "input_tokens": 10200000,
        "output_tokens": 3100000,
        "requests": 5800
      },
      {
        "model_provider": "anthropic",
        "model_name": "claude-sonnet-4-20250514",
        "total_cost_usd": 355.55,
        "input_tokens": 5034000,
        "output_tokens": 1467000,
        "requests": 3123
      }
    ]
  }
  ```
</ResponseExample>

## Cost Time Series

```
GET /cost/timeseries
```

Get cost data as a time series for charting.

| Parameter     | Type   | Default     | Description                |
| ------------- | ------ | ----------- | -------------------------- |
| `granularity` | string | `day`       | `hour`, `day`, `week`      |
| `from`        | string | 30 days ago | ISO 8601 date              |
| `to`          | string | Today       | ISO 8601 date              |
| `agent_id`    | string | -           | Filter to a specific agent |
| `team`        | string | -           | Filter to a specific team  |

```bash theme={null}
curl "https://api.meshai.dev/api/v1/cost/timeseries?granularity=day&from=2026-03-01" \
  -H "Authorization: Bearer msh_YOUR_API_KEY"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": [
      {
        "timestamp": "2026-03-01T00:00:00Z",
        "cost_usd": 72.34,
        "input_tokens": 890000,
        "output_tokens": 267000,
        "requests": 520
      },
      {
        "timestamp": "2026-03-02T00:00:00Z",
        "cost_usd": 68.90,
        "input_tokens": 845000,
        "output_tokens": 251000,
        "requests": 498
      }
    ]
  }
  ```
</ResponseExample>

## Budget Limits

Budget limits are an enforcement feature: once configured, the proxy blocks over-budget requests for the scope they apply to (global, a team, or a single agent). Creating or updating a limit requires a plan with enforcement entitlement (Starter and above); free-tier tenants get a `402` upgrade-required error. Reading limits and status, and deleting a limit, only require the `admin` scope.

### List Budget Limits

```
GET /budget/limits
```

List all budget limits configured for your tenant.

```bash theme={null}
curl https://api.meshai.dev/api/v1/budget/limits \
  -H "Authorization: Bearer msh_YOUR_ADMIN_KEY"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": [
      {
        "id": "01JBUDGET1LIMIT2ABC3DEF456",
        "tenant_id": "01JTENANT123ABC456DEF789",
        "team_id": null,
        "agent_id": "agt_abc123",
        "monthly_limit_usd": 500.00,
        "warn_threshold_pct": 80,
        "block_threshold_pct": 100,
        "enabled": true,
        "created_at": "2026-03-01T00:00:00Z",
        "updated_at": "2026-03-01T00:00:00Z"
      }
    ]
  }
  ```
</ResponseExample>

### Create a Budget Limit

```
POST /budget/limits
```

Create a budget limit for a scope. Set exactly one of `team_id` or `agent_id` to scope the limit; omit both for a tenant-wide (global) limit.

| Field                 | Type    | Required | Description                                                           |
| --------------------- | ------- | -------- | --------------------------------------------------------------------- |
| `team_id`             | string  | No       | Scope the limit to a team                                             |
| `agent_id`            | string  | No       | Scope the limit to a single agent                                     |
| `monthly_limit_usd`   | number  | Yes      | Monthly spend cap in USD (0-999999)                                   |
| `warn_threshold_pct`  | integer | No       | Percentage of the limit that triggers a warning (default `80`, 1-100) |
| `block_threshold_pct` | integer | No       | Percentage of the limit that blocks requests (default `100`, 1-200)   |
| `enabled`             | boolean | No       | Whether the limit is active (default `true`)                          |

```bash theme={null}
curl -X POST https://api.meshai.dev/api/v1/budget/limits \
  -H "Authorization: Bearer msh_YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_abc123",
    "monthly_limit_usd": 500.00,
    "warn_threshold_pct": 80,
    "block_threshold_pct": 100
  }'
```

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "id": "01JBUDGET1LIMIT2ABC3DEF456",
      "tenant_id": "01JTENANT123ABC456DEF789",
      "team_id": null,
      "agent_id": "agt_abc123",
      "monthly_limit_usd": 500.00,
      "warn_threshold_pct": 80,
      "block_threshold_pct": 100,
      "enabled": true,
      "created_at": "2026-03-01T00:00:00Z",
      "updated_at": "2026-03-01T00:00:00Z"
    }
  }
  ```
</ResponseExample>

### Update a Budget Limit

```
PATCH /budget/limits/{id}
```

Update an existing budget limit. All fields are optional; only the fields you include are changed.

| Field                 | Type    | Required | Description                           |
| --------------------- | ------- | -------- | ------------------------------------- |
| `monthly_limit_usd`   | number  | No       | Monthly spend cap in USD (0-999999)   |
| `warn_threshold_pct`  | integer | No       | Warning threshold percentage (1-100)  |
| `block_threshold_pct` | integer | No       | Blocking threshold percentage (1-200) |
| `enabled`             | boolean | No       | Whether the limit is active           |

```bash theme={null}
curl -X PATCH https://api.meshai.dev/api/v1/budget/limits/01JBUDGET1LIMIT2ABC3DEF456 \
  -H "Authorization: Bearer msh_YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "monthly_limit_usd": 750.00
  }'
```

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "id": "01JBUDGET1LIMIT2ABC3DEF456",
      "tenant_id": "01JTENANT123ABC456DEF789",
      "team_id": null,
      "agent_id": "agt_abc123",
      "monthly_limit_usd": 750.00,
      "warn_threshold_pct": 80,
      "block_threshold_pct": 100,
      "enabled": true,
      "created_at": "2026-03-01T00:00:00Z",
      "updated_at": "2026-03-18T09:15:00Z"
    }
  }
  ```
</ResponseExample>

### Delete a Budget Limit

```
DELETE /budget/limits/{id}
```

Delete a budget limit. Requires the `admin` scope.

```bash theme={null}
curl -X DELETE https://api.meshai.dev/api/v1/budget/limits/01JBUDGET1LIMIT2ABC3DEF456 \
  -H "Authorization: Bearer msh_YOUR_ADMIN_KEY"
```

Returns `204 No Content` on success.

### Budget Status

```
GET /budget/status
```

Get current spend versus limit for every configured scope (global, team, and agent).

```bash theme={null}
curl https://api.meshai.dev/api/v1/budget/status \
  -H "Authorization: Bearer msh_YOUR_ADMIN_KEY"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "scopes": [
        {
          "scope": "agent:agt_abc123",
          "limit_id": "01JBUDGET1LIMIT2ABC3DEF456",
          "monthly_limit_usd": 750.00,
          "current_spend_usd": 612.40,
          "percentage": 81.6,
          "warn_threshold_pct": 80,
          "block_threshold_pct": 100,
          "enabled": true
        }
      ]
    }
  }
  ```
</ResponseExample>