Cost API - MeshAI Documentation

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

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

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

Cost by Agent

GET /cost/by-agent

Break down costs per agent, sorted by cost descending.

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

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

Cost by Team

GET /cost/by-team

Break down costs per team.

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

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

Cost by Model

GET /cost/by-model

Break down costs per model.

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

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

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

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

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

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.

curl https://api.meshai.dev/api/v1/budget/limits \
  -H "Authorization: Bearer msh_YOUR_ADMIN_KEY"

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

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`)

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
  }'

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

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

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
  }'

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

Delete a Budget Limit

DELETE /budget/limits/{id}

Delete a budget limit. Requires the admin scope.

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).

curl https://api.meshai.dev/api/v1/budget/status \
  -H "Authorization: Bearer msh_YOUR_ADMIN_KEY"

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

​Cost Summary

​Cost by Agent

​Cost by Team

​Cost by Model

​Cost Time Series

​Budget Limits

​List Budget Limits

​Create a Budget Limit

​Update a Budget Limit

​Delete a Budget Limit

​Budget Status