Developer API

Access line items, daily rollups, and anomaly alerts programmatically. REST API with webhooks and Postman.

Get started

Download Postman Collection Claude Code (MCP)npm package Manage API keys

Quick Start

One command to fetch your cost data. Replace YOUR_KEY with an API key from Settings.

curl -X GET "https://stackspend-api.up.railway.app/api/v1/public/line-items?start_date=2025-01-01&end_date=2025-01-31&limit=10" \
  -H "X-API-Key: YOUR_KEY"

Overview

The Stack Spend API lets you pull cost data, rollups, and anomaly alerts for your organization. All endpoints require API key authentication and are available on the Business plan.

Base URL: https://stackspend-api.up.railway.app

For self-hosted or custom deployments, use your configured API URL.

Authentication

Create API keys in Settings → API Keys. Pass the key in the X-API-Key header.

curl -X GET "https://stackspend-api.up.railway.app/api/v1/public/line-items?start_date=2025-01-01&end_date=2025-01-31" \
  -H "X-API-Key: your_api_key_here"

Scopes

line_items:read — Cost line items
rollups:read — Daily rollups
anomalies:read — Anomaly alerts

API access requires the Business plan. Keys are shown only once at creation.

GET/api/v1/public/line-items

Cursor-paginated cost line items.

Parameter	Type	Description
start_date	string	YYYY-MM-DD (required)
end_date	string	YYYY-MM-DD (required)
limit	number	1–1000, default 50
cursor	string	From meta.next_cursor

curl -X GET "https://stackspend-api.up.railway.app/api/v1/public/line-items?start_date=2025-01-01&end_date=2025-01-31&limit=10" \
  -H "X-API-Key: YOUR_KEY"

Response

{
  "data": [
    {
      "id": "uuid",
      "usage_date": "2025-01-15",
      "provider_type": "aws",
      "provider_service": "Amazon EC2",
      "net_amount_usd": 42.50,
      "currency_original": "USD",
      "project_id": null,
      "user_email": null
    }
  ],
  "meta": {
    "next_cursor": "2025-01-15:uuid",
    "has_more": true,
    "request_id": "uuid"
  }
}

GET/api/v1/public/rollups/daily

Pre-aggregated daily costs by provider, service, or category.

Required: start_date, end_date, group_by (provider | service | category)

curl -X GET "https://stackspend-api.up.railway.app/api/v1/public/rollups/daily?start_date=2025-01-01&end_date=2025-01-31&group_by=provider" \
  -H "X-API-Key: YOUR_KEY"

Response

{
  "data": [
    {
      "date": "2025-01-15",
      "cost_usd": 123.45,
      "provider_type": "aws",
      "service": null,
      "category": null
    }
  ],
  "meta": {
    "group_by": "provider",
    "range": { "start": "2025-01-01", "end": "2025-01-31" }
  }
}

GET/api/v1/public/anomalies

Spend anomaly alerts. Optional: limit, since, provider_type, severity, status.

curl -X GET "https://stackspend-api.up.railway.app/api/v1/public/anomalies?limit=10" \
  -H "X-API-Key: YOUR_KEY"

Response

{
  "data": [
    {
      "id": "uuid",
      "provider_type": "openai",
      "service": "gpt-4",
      "detected_date": "2025-01-15",
      "actual_cost": 450,
      "expected_cost": 280,
      "deviation_percent": 60.7,
      "severity": "high",
      "alert_type": "spike"
    }
  ]
}

Webhooks

Configure webhook endpoints in Settings → Webhooks to receive anomaly alerts via HTTP POST. Event type: anomaly.created.

Verification

Each request includes X-StackSpend-Signature (HMAC-SHA256 of timestamp.body). Verify using the signing secret shown once when creating the endpoint.

Headers

X-StackSpend-Event — Event type
X-StackSpend-Event-Id — Unique event ID
X-StackSpend-Timestamp — Unix timestamp
X-StackSpend-Signature — sha256=hex(signature)

Error Codes

Errors return { error: { code, message } }.

UNAUTHORIZED — Missing or invalid API key
FORBIDDEN — Admin required (for key management)
INVALID_SCOPE — Key lacks required scope
PLAN_RESTRICTED — API access requires Business plan
VALIDATION_ERROR — Invalid parameters
INTERNAL_ERROR — Server error

← Back to Guides Create API key →