Overview

Programmatic access to spend, usage, tokens, and latency

The Usage API lets you query your Sail usage from scripts, CLIs, or dashboards, the same data shown on the dashboard in app.sailresearch.com. It covers two families:

• Billing & cost: combined spend, an Inference and Sailboxes product split, Sailbox line-item spend, credit balance, burn rate, days remaining, per-model cost rankings, per-API-key inference usage, and inference token counters.
• Operational activity & latency: request counts and time series, recent requests, task activity, and turn/trajectory latency distributions.

Plan history limits

Your plan limits how far back you can read usage data.

• Free organizations see 7 days of charts, and the last hour of request activity.
• Pro organizations can select rolling ranges up to 30 days and see the last 24 hours of request activity.
• Enterprise organizations can also select period (the current billing period) and read full usage history through the API, subject to retention.

Every response that accepts a range sets plan_limited: true when a plan limit changed the request (false otherwise), and indicates the range actually applied in effective_range.

Base URL

https://api.sailresearch.com

Authentication

All requests require a Bearer API key in the Authorization header.

This is the same API key you use for the inference API at api.sailresearch.com. Create or manage keys from the Sail dashboard.

import requests

headers = {"Authorization": "Bearer YOUR_SAIL_API_KEY"}
params = {"bucket_size": "1h", "environment": "all"}
resp = requests.get(
    "https://api.sailresearch.com/v2/usage",
    headers=headers,
    params=params,
)
print(resp.json())

Product-aware spend

Use the summary endpoint to read combined spend and its exact product split:

curl -s -H "Authorization: Bearer $SAIL_API_KEY" \
  "https://api.sailresearch.com/v2/usage/summary?range=30d" | \
  jq '{period_spend, product_spend, sailbox_spend}'

product_spend always has exactly two buckets, inference and sailboxes, which add up to period_spend. Inference token, model, completion-window, and latency metrics exclude Sailbox usage. See Usage API endpoints for the full accounting contract and field definitions.

Endpoints

Full reference for every usage route: parameters, response shapes, error formats, and headers.

Usage data may have a slight delay and is not real-time. Billing-derived fields (spend, balance, per-API-key usage, token counters) are sourced from metered billing data and can lag the most recent minutes more than the operational activity and latency endpoints.

Monetary fields are fractional USD cents (floats), and token fields are raw token counts. See Endpoints for the exact units per field.