ephemerisAPI docs

Ephemeris API · v1

Time-series forecasting through one API.

Send a time series and get a probabilistic forecast back. Choose one model, let Ephemeris choose, or run an ensemble. Credits are reserved up front and you are charged only for the models that ran.

Base URLhttps://ephemeris.cascade.industries/api/v1
01

Start here

Quickstart

Create an API key in the dashboard, add credits, and submit a forecast. Keep the same idempotency key when retrying an identical request.

cURLUTF-8
curl --request POST \
  --url https://ephemeris.cascade.industries/api/v1/forecast \
  --header "Authorization: Bearer pc_live_your_key" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: forecast-2026-08-26-001" \
  --data '{
    "mode": "route",
    "series": [{
      "values": [100.2, 101.4, 99.8, 103.1, 104.6, 102.2],
      "freq": "H"
    }],
    "horizon": 24,
    "quantiles": [0.1, 0.5, 0.9]
  }'
02

Security

Authentication

Bearer API keys

Every v1 endpoint requires an Ephemeris API key in the Authorization header. Store keys server-side and revoke any key that may have been exposed.

HeaderUTF-8
Authorization: Bearer pc_live_your_key

Sign in from a terminal or agent

A CLI or agent can get a key without anyone copying it: the OAuth 2.0 device flow (RFC 8628), the same as gh auth login. It shows the person a short code and a link; they sign in or sign up, check the page shows the same code, and approve. The key comes back to the tool once, and appears on the API keys page under the name the tool gave, where it can be revoked. Codes expire after 10 minutes.

Device flowUTF-8
# 1. Start: no API key needed
curl -s -X POST https://ephemeris.cascade.industries/api/v1/device/code \
  -H "Content-Type: application/json" \
  -d '{"client":"my-agent","name":"my-agent on laptop"}'
# -> {"device_code":"...","user_code":"WDJB-MJHT",
#     "verification_uri_complete":"https://.../dashboard/device?code=WDJB-MJHT",
#     "expires_in":600,"interval":5}

# 2. Show the person user_code and open verification_uri_complete.
# 3. Every interval seconds, until approved:
curl -s -X POST https://ephemeris.cascade.industries/api/v1/device/token \
  -H "Content-Type: application/json" -d '{"device_code":"..."}'
# -> {"error":"authorization_pending"}  keep waiting
# -> {"error":"slow_down"}              wait 5 s longer from now on
# -> {"key":"pc_live_..."}              done (returned once)
03

Reference

Endpoints

GET/api/v1/models

List models

Lists available models with their price and capabilities. History length has no billing multiplier.

GET/api/v1/balance

Get balance

Returns the credits you can spend now. Credits reserved by in-progress forecasts are excluded.

POST/api/v1/forecast

Run a forecast

Runs a forecast and returns the result with the models used and the cost.

POST/api/v1/feedback

Send actuals

Optional and free. Send the values that actually happened for one of your forecasts, as request_id (its meta.request_id) and actuals (one path per series, in order). They tune the ensemble weights and routing.

GET/api/v1/usage

List usage

Returns paginated forecast request history. Supports limit and offset query parameters.

04

Core operation

Forecast request

explicit

Single model

You pick the model. Use this when you already know which one fits your data.

route

Auto-select

Ephemeris picks the best model for your series. If that model fails, it falls back to a small ensemble.

ensemble

Ensemble

Runs all compatible models and blends the results. Models that fail are left out and not charged.

FieldTypeRequirement
modestringRequired: explicit, route, or ensemble.
modelstringRequired only for explicit mode.
seriesobject[]One or more entries containing numeric values.
series[].valuesnumber[] | number[][]Flat for univariate; nested for multivariate.
series[].freqstringOptional per-series frequency; mixed batches are split safely upstream.
series[].covariatesobjectOptional aligned past and known-future named channels.
context_lenintegerHow many recent observations to use. Defaults to 256. Does not affect pricing.
horizonintegerOptional; defaults to 64.
quantilesnumber[]Optional values strictly between 0 and 1.
top_kintegerOptional ensemble-only model limit from 1 to 16.
combinestringHow ensemble results are blended. Mixture averages distributions; vincentize averages quantiles. Defaults to mixture.

Safe retries

Use an idempotency key

Keys accept 8–128 letters, numbers, dots, underscores, colons, or hyphens. Completed retries return the stored response without running or charging for the forecast again.

Request headerUTF-8
Idempotency-Key: forecast-2026-08-26-001
Example responseUTF-8
{
  "forecasts": [
    {
      "quantiles": {
        "0.1": [103.8, 104.1, 104.5],
        "0.5": [105.2, 105.7, 106.1],
        "0.9": [106.9, 107.4, 108.0]
      }
    }
  ],
  "meta": {
    "gateway_request_id": "req_01J...",
    "request_id": "model_01J...",
    "models_used": ["chronos2"],
    "model_revisions": { "chronos2": "3f9c1e0a..." },
    "billing": {
      "settled_mc": "12",
      "balance_mc": "4988"
    }
  }
}

forecasts has one entry per input series, in request order. Univariate entries return flat horizon arrays; multivariate entries return nested arrays. Quantile keys are decimal strings such as 0.5. meta.model_revisions names the exact weights (Hugging Face commit) each model served, so a forecast can be tied to a model revision, not just an API version.

05

Model Context Protocol

Agents (MCP)

Ephemeris is a remote MCP server. Any client that speaks the Model Context Protocol over Streamable HTTP can use it: coding agents, desktop assistants, agent frameworks and server-side SDKs alike. There is nothing to install and no client is preferred; the endpoint and one header are all a client needs. Step-by-step setup for each client is in How to give Claude, Cursor or any AI agent a forecasting tool.

MCP endpointhttps://ephemeris.cascade.industries/api/mcp

Connect your account

Create an API key on the API keys page and add credits. Register the endpoint in your client with the key as a bearer header. Every call the agent makes is charged to that key's account and shows up in usage. Revoke the key to disconnect the agent.

Most clients accept the JSON on the right as-is. Client-specific shapes follow below.

Generic config (mcpServers)UTF-8
{
  "mcpServers": {
    "ephemeris": {
      "url": "https://ephemeris.cascade.industries/api/mcp",
      "headers": {
        "Authorization": "Bearer pc_live_your_key"
      }
    }
  }
}
ClientWhere
Cursor.cursor/mcp.json
Claude Codeterminal, or .mcp.json with the generic config
VS Code (Copilot).vscode/mcp.json
Codex CLI~/.codex/config.toml, key read from an environment variable
Gemini CLI~/.gemini/settings.json
Claude Desktopclaude_desktop_config.json, through the mcp-remote bridge
OpenAI Responses API and Agents SDKhosted MCP tool
Anthropic Messages APIMCP connector
Any other client or SDKStreamable HTTP transport

Cursor

.cursor/mcp.json

Add to Cursor ↗ Then replace YOUR_EPHEMERIS_API_KEY in Cursor's MCP settings, or use Add to Cursor in the dashboard after creating a key: it fills the key in for you.

ConfigUTF-8
{
  "mcpServers": {
    "ephemeris": {
      "url": "https://ephemeris.cascade.industries/api/mcp",
      "headers": {
        "Authorization": "Bearer pc_live_your_key"
      }
    }
  }
}

Claude Code

terminal, or .mcp.json with the generic config

ConfigUTF-8
claude mcp add --transport http ephemeris \
  https://ephemeris.cascade.industries/api/mcp \
  --header "Authorization: Bearer pc_live_your_key"

VS Code (Copilot)

.vscode/mcp.json

ConfigUTF-8
{
  "servers": {
    "ephemeris": {
      "type": "http",
      "url": "https://ephemeris.cascade.industries/api/mcp",
      "headers": {
        "Authorization": "Bearer pc_live_your_key"
      }
    }
  }
}

Codex CLI

~/.codex/config.toml, key read from an environment variable

ConfigUTF-8
[mcp_servers.ephemeris]
url = "https://ephemeris.cascade.industries/api/mcp"
bearer_token_env_var = "EPHEMERIS_API_KEY"

Gemini CLI

~/.gemini/settings.json

ConfigUTF-8
{
  "mcpServers": {
    "ephemeris": {
      "httpUrl": "https://ephemeris.cascade.industries/api/mcp",
      "headers": {
        "Authorization": "Bearer pc_live_your_key"
      }
    }
  }
}

Claude Desktop

claude_desktop_config.json, through the mcp-remote bridge

ConfigUTF-8
{
  "mcpServers": {
    "ephemeris": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://ephemeris.cascade.industries/api/mcp",
        "--header", "Authorization: Bearer pc_live_your_key"
      ]
    }
  }
}

OpenAI Responses API and Agents SDK

hosted MCP tool

ConfigUTF-8
"tools": [{
  "type": "mcp",
  "server_label": "ephemeris",
  "server_url": "https://ephemeris.cascade.industries/api/mcp",
  "headers": { "Authorization": "Bearer pc_live_your_key" }
}]

Anthropic Messages API

MCP connector

ConfigUTF-8
"mcp_servers": [{
  "type": "url",
  "url": "https://ephemeris.cascade.industries/api/mcp",
  "name": "ephemeris",
  "authorization_token": "pc_live_your_key"
}]

Any other client or SDK

Streamable HTTP transport

ConfigUTF-8
URL:     https://ephemeris.cascade.industries/api/mcp
Header:  Authorization: Bearer pc_live_your_key

Stateless: no session id, no SSE stream to keep open.
Stdio-only clients: npx mcp-remote <url> --header "Authorization: Bearer <key>"

Follow the CLI installation and forecasting guide, or read the complete agent command reference. The standalone CLI is available on npm: install with npm install --global ephemeris-cli@0.5.1 (Node.js 22.23.4+, 24.22.1+ or 26.12.1+), then run ephemeris --help or ephemeris version --json. Hosted tools update automatically. Reconnect or start a new conversation to refresh tools cached by your client. Existing npm bridges discover new hosted tools without a package upgrade. Image and attachment display depends on your client; the server requires Streamable HTTP support.

toolget_version

Public, no-key version diagnostics: hosted server version, nullable build commit and supported artifact schemas. No inference or charge. For your installed CLI, use ephemeris version --json; server and package versions are independent.

tooldescribe_forecast

Deterministic interpretation of a saved Ephemeris artifact: explicit baselines, billing units and uncertainty limits. No new inference or forecast charge. Pass the artifact object, not a local path or URL.

toolplot_forecast

Render a saved artifact as an inline PNG preview or SVG attachment, without new inference. Includes observed history, forecast boundary, median and nominal quantile bands. Save attachments in your client; no permanent hosted URL is created.

toolforecast

Runs the same paid pipeline as POST /api/v1/forecast. Retain an idempotency_key before submission. Returns the forecast and, by default, a portable artifact with full history, billing and local context for client-side saving. Replay depends on server retention.

toollist_models

The live model panel with prices and context caps.

toolget_balance

Spendable credits, excluding holds from in-flight forecasts.

toolget_usage

Newest-first request log with pagination.

The transport is stateless Streamable HTTP; there is no session to keep alive. Every forecast result includes settled_mc and balance_mc so the agent, and you, can see what each call cost. A missing or revoked key returns 401; an empty balance returns a tool error carrying a top-up link the agent can hand back to you. OAuth sign-in for one-click connectors is planned; today every client needs a key.

06

Millicredits

Pricing

Cost per model

price_per_kslot_mc × slots × ceil(horizon / 64)

Each model is priced per series and per 64 forecast steps. History length does not increase the charge.

1 credit = 1,000 mc

“mc” means millicredits.

Reserve, then charge

Before a forecast runs, Ephemeris reserves the maximum possible cost. You are charged only for models that returned a result, and the rest is released.

Live prices

Read model prices from GET /api/v1/models. History length has no billing multiplier.

07

Request guardrails

Limits

Series64per request
Series slots256variates total
Context16,384points per variate
Horizon4,096forecast steps
Quantiles21per request
JSON body10 MBmaximum

Slots × horizon × quantiles must not exceed 120,000 output values. Requests without explicit quantiles are budgeted as 21 quantiles. Forecasts use a token bucket of 10 requests per minute with a burst of 20. Calls waiting longer than 30 seconds return 429 with guidance on when to retry.

08

Recovery

Errors

400

Invalid request

The body, limits, mode, model, or pagination is invalid.

401

Unauthorized

The bearer API key is missing, invalid, or revoked.

402

Insufficient credits

Top up using the returned topup_url, then retry.

409

Idempotency conflict

The key is in progress or was reused with a different body.

429

Rate limited

Retry after the number of seconds in Retry-After.

503

Temporarily unavailable

Pricing or the model service is unavailable.

Ready to forecast

Create a key and run your first request.