The Costs API provides spending breakdowns, budget management, and SLA monitoring for your AI agents.

GET /api/costs/breakdown

Get cost breakdown by agent, model, or time period

Parameters:

Param	Type	Description
`period`	string	`1d`, `7d`, `30d`, `90d` (default `30d`)
`groupBy`	string	`agent`, `model`, or `environment` (default `agent`)
`agentId`	string	Scope to a specific agent

Response (200):

{
  "period": "30d",
  "groupBy": "agent",
  "totalCostUsd": 184.32,
  "data": [
    {
      "agentId": "agent_abc123",
      "agentName": "customer-support",
      "totalCostUsd": 128.41,
      "inputTokens": 84200000,
      "outputTokens": 21000000,
      "traceCount": 42000,
      "avgCostPerTrace": 0.00306
    },
    {
      "agentId": "agent_def456",
      "agentName": "invoice-processor",
      "totalCostUsd": 55.91,
      "inputTokens": 22000000,
      "outputTokens": 8400000,
      "traceCount": 12000,
      "avgCostPerTrace": 0.00466
    }
  ]
}

import Rivano from '@rivano/sdk';
const rivano = new Rivano({ apiKey: process.env.RIVANO_API_KEY! });

const breakdown = await rivano.costs.breakdown({ period: '30d', groupBy: 'agent' });
for (const entry of breakdown.data) {
  console.log(`${entry.agentName}: $${entry.totalCostUsd.toFixed(2)}`);
}

curl "https://api.rivano.ai/api/costs/breakdown?period=30d&groupBy=agent" \
  -H "Authorization: Bearer rv_api_..."

GET /api/costs/budgets

List all configured budgets

Response (200):

{
  "data": [
    {
      "id": "budget_abc123",
      "name": "customer-support-monthly",
      "agentId": "agent_abc123",
      "agentName": "customer-support",
      "period": "monthly",
      "limitUsd": 500,
      "currentUsd": 128.41,
      "percentUsed": 25.7,
      "resetAt": "2026-05-01T00:00:00Z"
    }
  ],
  "total": 3
}

const budgets = await rivano.costs.listBudgets();
budgets.data.forEach(b => {
  console.log(`${b.name}: ${b.percentUsed.toFixed(1)}% of $${b.limitUsd}`);
});

curl https://api.rivano.ai/api/costs/budgets \
  -H "Authorization: Bearer rv_api_..."

POST /api/costs/budgets

Create a spending budget

Request body:

{
  "name": "invoice-processor-monthly",
  "agentId": "agent_def456",
  "period": "monthly",
  "limitUsd": 200
}

Field	Required	Description
`name`	Yes	Unique budget name
`agentId`	Yes	Agent to track
`period`	Yes	`daily`, `weekly`, or `monthly`
`limitUsd`	Yes	USD spending limit

Response (201): Budget object (same shape as list item).

await rivano.costs.createBudget({
  name: 'invoice-processor-monthly',
  agentId: 'agent_def456',
  period: 'monthly',
  limitUsd: 200,
});

curl -X POST https://api.rivano.ai/api/costs/budgets \
  -H "Authorization: Bearer rv_api_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "invoice-processor-monthly", "agentId": "agent_def456", "period": "monthly", "limitUsd": 200}'

DELETE /api/costs/budgets/:id

Delete a budget

Response (200):

{ "success": true }

await rivano.costs.deleteBudget('budget_abc123');

curl -X DELETE https://api.rivano.ai/api/costs/budgets/budget_abc123 \
  -H "Authorization: Bearer rv_api_..."

GET /api/costs/sla

List all SLA targets

Response (200):

{
  "data": [
    {
      "id": "sla_abc123",
      "name": "customer-support-sla",
      "agentId": "agent_abc123",
      "agentName": "customer-support",
      "p99LatencyMs": 3000,
      "errorRatePercent": 1.0,
      "evaluationPeriod": "1h",
      "currentP99Ms": 1840,
      "currentErrorRate": 0.6,
      "status": "healthy"
    }
  ],
  "total": 2
}

curl https://api.rivano.ai/api/costs/sla \
  -H "Authorization: Bearer rv_api_..."

POST /api/costs/sla

Create an SLA target

Request body:

{
  "name": "customer-support-sla",
  "agentId": "agent_abc123",
  "p99LatencyMs": 3000,
  "errorRatePercent": 1.0,
  "evaluationPeriod": "1h"
}

Response (201): SLA object.

await rivano.costs.createSla({
  name: 'customer-support-sla',
  agentId: 'agent_abc123',
  p99LatencyMs: 3000,
  errorRatePercent: 1.0,
  evaluationPeriod: '1h',
});

curl -X POST https://api.rivano.ai/api/costs/sla \
  -H "Authorization: Bearer rv_api_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "customer-support-sla",
    "agentId": "agent_abc123",
    "p99LatencyMs": 3000,
    "errorRatePercent": 1.0,
    "evaluationPeriod": "1h"
  }'

GET /api/costs/sla/violations

List SLA violations

Parameters:

Param	Type	Description
`period`	string	Look-back window: `1h`, `24h`, `7d` (default `24h`)
`slaId`	string	Filter by SLA ID

Response (200):

{
  "data": [
    {
      "id": "violation_abc123",
      "slaId": "sla_abc123",
      "slaName": "customer-support-sla",
      "agentName": "customer-support",
      "periodStart": "2026-04-04T08:00:00Z",
      "periodEnd": "2026-04-04T09:00:00Z",
      "violationType": "latency",
      "targetP99Ms": 3000,
      "actualP99Ms": 4820,
      "targetErrorRate": 1.0,
      "actualErrorRate": 0.7
    }
  ],
  "total": 1
}

const violations = await rivano.costs.listSlaViolations({ period: '24h' });
if (violations.total > 0) {
  console.warn(`${violations.total} SLA violations in the last 24h`);
}

curl "https://api.rivano.ai/api/costs/sla/violations?period=24h" \
  -H "Authorization: Bearer rv_api_..."

Cost Tracking Guide — Step-by-step setup
Traces API — Underlying trace data
SDK Costs — Typed SDK wrapper
Dashboard Observability — Costs page walkthrough

Costs API

Related