REST API Reference

The Ladger REST API allows you to query metrics, manage projects, and access data programmatically.

Base URL

https://ladger.pages.dev/api/v1

For self-hosted deployments:

https://your-domain.com/api/v1

Authentication

All API requests require a Bearer token:

curl -H "Authorization: Bearer ladger_sk_live_your_api_key" \
  https://ladger.pages.dev/api/v1/metrics

Endpoints

Ingest Spans

Submit spans for a flow.

POST /v1/ingest

Request Body

{
  "flowName": "my-chatbot",
  "sessionId": "sess-abc123",
  "spans": [
    {
      "id": "span-123",
      "name": "chat-completion",
      "startTime": 1705123456789,
      "endTime": 1705123457123,
      "parentId": null,
      "attributes": {
        "user.id": "user-123"
      },
      "costEvent": {
        "provider": "openai",
        "model": "gpt-4o",
        "inputTokens": 150,
        "outputTokens": 50,
        "costUsd": 0.0015
      }
    }
  ]
}

Response

{
  "success": true,
  "spansReceived": 1,
  "traceId": "trace-xyz789"
}

Get Traces

List traces for a flow.

GET /v1/traces

Query Parameters

Parameter	Type	Description
`flowName`	string	Filter by flow name
`startDate`	string	ISO date (e.g., `2024-01-01`)
`endDate`	string	ISO date
`limit`	number	Max results (default: 50, max: 100)
`offset`	number	Pagination offset

Example

curl "https://ladger.pages.dev/api/v1/traces?flowName=my-chatbot&limit=10" \
  -H "Authorization: Bearer ladger_sk_live_..."

Response

{
  "traces": [
    {
      "id": "trace-123",
      "flowName": "my-chatbot",
      "sessionId": "sess-abc",
      "startTime": "2024-01-15T10:30:00Z",
      "endTime": "2024-01-15T10:30:02Z",
      "durationMs": 2000,
      "spanCount": 3,
      "totalCost": 0.0045
    }
  ],
  "total": 1234,
  "limit": 10,
  "offset": 0
}

Get Trace Details

Get full details for a specific trace.

GET /v1/traces/:traceId

Response

{
  "id": "trace-123",
  "flowName": "my-chatbot",
  "sessionId": "sess-abc",
  "startTime": "2024-01-15T10:30:00Z",
  "endTime": "2024-01-15T10:30:02Z",
  "spans": [
    {
      "id": "span-1",
      "name": "handle-request",
      "startTime": 1705312200000,
      "endTime": 1705312202000,
      "durationMs": 2000,
      "parentId": null,
      "attributes": {},
      "costEvent": null
    },
    {
      "id": "span-2",
      "name": "chat-completion",
      "parentId": "span-1",
      "startTime": 1705312200100,
      "endTime": 1705312201900,
      "durationMs": 1800,
      "attributes": {},
      "costEvent": {
        "provider": "openai",
        "model": "gpt-4o",
        "inputTokens": 150,
        "outputTokens": 50,
        "costUsd": 0.0015
      }
    }
  ],
  "totalCost": 0.0015
}

Get Cost Metrics

Retrieve aggregated cost metrics.

GET /v1/metrics/costs

Query Parameters

Parameter	Type	Description
`flowName`	string	Filter by flow
`startDate`	string	Start date (required)
`endDate`	string	End date (required)
`groupBy`	string	`provider`, `model`, `flow`, `day`

Example

curl "https://ladger.pages.dev/api/v1/metrics/costs?startDate=2024-01-01&endDate=2024-01-31&groupBy=model" \
  -H "Authorization: Bearer ladger_sk_live_..."

Response

{
  "totalCost": 2450.50,
  "totalRequests": 156234,
  "avgCostPerRequest": 0.0157,
  "breakdown": [
    {
      "model": "gpt-4o",
      "cost": 1245.00,
      "requests": 45230,
      "percentage": 50.8
    },
    {
      "model": "gpt-4o-mini",
      "cost": 89.50,
      "requests": 89450,
      "percentage": 3.7
    }
  ],
  "trend": [
    { "date": "2024-01-01", "cost": 78.50 },
    { "date": "2024-01-02", "cost": 82.30 }
  ]
}

Get Classification Summary

Retrieve task classification breakdown.

GET /v1/classification/summary

Query Parameters

Parameter	Type	Description
`flowName`	string	Filter by flow
`startDate`	string	Start date
`endDate`	string	End date

Response

{
  "taskKindDistribution": [
    { "kind": "qa_retrieval", "count": 45230, "percentage": 35 },
    { "kind": "classification", "count": 32150, "percentage": 25 },
    { "kind": "data_extraction", "count": 23180, "percentage": 18 },
    { "kind": "summarization", "count": 15420, "percentage": 12 },
    { "kind": "code_generation", "count": 9010, "percentage": 7 },
    { "kind": "other", "count": 3870, "percentage": 3 }
  ],
  "complexityDistribution": [
    { "level": "low", "count": 91234, "percentage": 58 },
    { "level": "medium", "count": 44012, "percentage": 28 },
    { "level": "high", "count": 21988, "percentage": 14 }
  ],
  "optimizationOpportunities": [
    {
      "spanName": "classify-intent",
      "currentModel": "gpt-4o",
      "suggestedModel": "gpt-3.5-turbo",
      "estimatedMonthlySavings": 2100,
      "qualityConfidence": 0.97
    }
  ]
}

List Flows

Get all flows for a project.

GET /v1/flows

Response

{
  "flows": [
    {
      "name": "customer-support",
      "lastActivity": "2024-01-15T10:30:00Z",
      "totalRequests": 52340,
      "totalCost": 1256.00,
      "avgCostPerRequest": 0.024
    },
    {
      "name": "content-generator",
      "lastActivity": "2024-01-15T09:45:00Z",
      "totalRequests": 38210,
      "totalCost": 726.00,
      "avgCostPerRequest": 0.019
    }
  ]
}

Create Simulation

Create a new optimization simulation.

POST /v1/simulations

Request Body

{
  "flowName": "customer-support",
  "spanName": "classify-intent",
  "dateRange": {
    "start": "2024-01-01",
    "end": "2024-01-31"
  },
  "sampleSize": 500,
  "change": {
    "model": "gpt-3.5-turbo"
  },
  "qualityThreshold": 0.95
}

Response

{
  "id": "sim-123",
  "status": "queued",
  "estimatedDuration": 120,
  "createdAt": "2024-01-15T10:30:00Z"
}

Get Simulation Results

GET /v1/simulations/:simulationId/results

Response

{
  "id": "sim-123",
  "status": "completed",
  "results": {
    "requestsTested": 500,
    "qualityScore": 0.972,
    "passed": true,
    "originalCost": 12.50,
    "simulatedCost": 0.87,
    "savings": 11.63,
    "savingsPercentage": 93,
    "failures": [
      {
        "requestId": "req-456",
        "originalOutput": "billing_inquiry",
        "simulatedOutput": "general_question",
        "similarityScore": 0.78
      }
    ]
  },
  "completedAt": "2024-01-15T10:32:00Z"
}

Error Responses

All errors follow this format:

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or expired",
    "details": {}
  }
}

Error Codes

Code	HTTP Status	Description
`INVALID_API_KEY`	401	Invalid or missing API key
`FORBIDDEN`	403	No access to resource
`NOT_FOUND`	404	Resource not found
`VALIDATION_ERROR`	400	Invalid request parameters
`RATE_LIMITED`	429	Too many requests
`INTERNAL_ERROR`	500	Server error

Rate Limits

Plan	Requests/minute	Requests/day
Free	60	1,000
Pro	300	50,000
Enterprise	Custom	Custom

Rate limit headers are included in responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1705312260

SDKs

Official SDKs that use this API:

TypeScript/Node.js: @ladger/sdk (npm)
Python: Coming soon
Go: Coming soon