Costs

Stevora tracks LLM token usage and costs for every workflow run. Use the cost endpoints to inspect per-run spending or get an aggregated summary across your workspace.

Get Cost for a Workflow Run

GET /v1/workflow-runs/:id/cost

Returns the total LLM cost breakdown for a specific workflow run.

Path Parameters

Parameter	Type	Description
`id`	`string`	The workflow run ID

Example Request

curl https://api.stevora.dev/v1/workflow-runs/wfrun_def456/cost \
  -H "x-api-key: stv_your_api_key"

Response `200 OK`

{
  "success": true,
  "data": {
    "workflowRunId": "wfrun_def456",
    "totalCostUsd": 0.0342,
    "totalInputTokens": 1520,
    "totalOutputTokens": 890,
    "calls": [
      {
        "stepName": "generate-welcome-email",
        "model": "gpt-4o",
        "inputTokens": 245,
        "outputTokens": 312,
        "costUsd": 0.0087,
        "createdAt": "2026-04-02T12:00:05.100Z"
      },
      {
        "stepName": "generate-summary",
        "model": "gpt-4o",
        "inputTokens": 680,
        "outputTokens": 410,
        "costUsd": 0.0163,
        "createdAt": "2026-04-02T12:00:10.200Z"
      },
      {
        "stepName": "classify-intent",
        "model": "claude-sonnet-4-20250514",
        "inputTokens": 595,
        "outputTokens": 168,
        "costUsd": 0.0092,
        "createdAt": "2026-04-02T12:00:12.500Z"
      }
    ]
  }
}

Error Responses

Status	Code	Cause
401	`AUTH_ERROR`	Missing or invalid API key
404	`NOT_FOUND`	Workflow run not found or belongs to another workspace

Get Workspace Cost Summary

GET /v1/cost/summary

Returns aggregated LLM costs across all workflow runs in your workspace. Use the from and to query parameters to scope the summary to a date range.

Query Parameters

Parameter	Type	Default	Description
`from`	`string`	--	Start of date range (ISO 8601 format, e.g., `2026-04-01T00:00:00Z`)
`to`	`string`	--	End of date range (ISO 8601 format, e.g., `2026-04-30T23:59:59Z`)

Both parameters are optional. If omitted, the summary covers all time.

Example Request

# Costs for April 2026
curl "https://api.stevora.dev/v1/cost/summary?from=2026-04-01T00:00:00Z&to=2026-04-30T23:59:59Z" \
  -H "x-api-key: stv_your_api_key"

Response `200 OK`

{
  "success": true,
  "data": {
    "workspaceId": "ws_xyz789",
    "from": "2026-04-01T00:00:00.000Z",
    "to": "2026-04-30T23:59:59.000Z",
    "totalCostUsd": 12.47,
    "totalInputTokens": 425000,
    "totalOutputTokens": 198000,
    "totalRuns": 156,
    "byModel": [
      {
        "model": "gpt-4o",
        "costUsd": 8.32,
        "inputTokens": 310000,
        "outputTokens": 145000,
        "calls": 230
      },
      {
        "model": "claude-sonnet-4-20250514",
        "costUsd": 4.15,
        "inputTokens": 115000,
        "outputTokens": 53000,
        "calls": 89
      }
    ]
  }
}

Example: All-Time Summary

curl https://api.stevora.dev/v1/cost/summary \
  -H "x-api-key: stv_your_api_key"

Error Responses

Status	Code	Cause
400	`VALIDATION_ERROR`	Invalid date format in `from` or `to` parameter
401	`AUTH_ERROR`	Missing or invalid API key

Costs

On this page