/api/v1/modelsList models
Lists available models with their price and capabilities. History length has no billing multiplier.
Ephemeris API · v1
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.
https://ephemeris.cascade.industries/api/v1Start here
Create an API key in the dashboard, add credits, and submit a forecast. Keep the same idempotency key when retrying an identical request.
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]
}'Security
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.
Authorization: Bearer pc_live_your_keyA 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.
# 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)Reference
/api/v1/modelsLists available models with their price and capabilities. History length has no billing multiplier.
/api/v1/balanceReturns the credits you can spend now. Credits reserved by in-progress forecasts are excluded.
/api/v1/forecastRuns a forecast and returns the result with the models used and the cost.
/api/v1/feedbackOptional 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.
/api/v1/usageReturns paginated forecast request history. Supports limit and offset query parameters.
Core operation
You pick the model. Use this when you already know which one fits your data.
Ephemeris picks the best model for your series. If that model fails, it falls back to a small ensemble.
Runs all compatible models and blends the results. Models that fail are left out and not charged.
| Field | Type | Requirement |
|---|---|---|
mode | string | Required: explicit, route, or ensemble. |
model | string | Required only for explicit mode. |
series | object[] | One or more entries containing numeric values. |
series[].values | number[] | number[][] | Flat for univariate; nested for multivariate. |
series[].freq | string | Optional per-series frequency; mixed batches are split safely upstream. |
series[].covariates | object | Optional aligned past and known-future named channels. |
context_len | integer | How many recent observations to use. Defaults to 256. Does not affect pricing. |
horizon | integer | Optional; defaults to 64. |
quantiles | number[] | Optional values strictly between 0 and 1. |
top_k | integer | Optional ensemble-only model limit from 1 to 16. |
combine | string | How ensemble results are blended. Mixture averages distributions; vincentize averages quantiles. Defaults to mixture. |
Safe retries
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.
Idempotency-Key: forecast-2026-08-26-001{
"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.
Model Context Protocol
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.
https://ephemeris.cascade.industries/api/mcpCreate 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.
{
"mcpServers": {
"ephemeris": {
"url": "https://ephemeris.cascade.industries/api/mcp",
"headers": {
"Authorization": "Bearer pc_live_your_key"
}
}
}
}| Client | Where |
|---|---|
| Cursor | .cursor/mcp.json |
| Claude Code | terminal, 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 Desktop | claude_desktop_config.json, through the mcp-remote bridge |
| OpenAI Responses API and Agents SDK | hosted MCP tool |
| Anthropic Messages API | MCP connector |
| Any other client or SDK | Streamable HTTP transport |
.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.
{
"mcpServers": {
"ephemeris": {
"url": "https://ephemeris.cascade.industries/api/mcp",
"headers": {
"Authorization": "Bearer pc_live_your_key"
}
}
}
}terminal, or .mcp.json with the generic config
claude mcp add --transport http ephemeris \
https://ephemeris.cascade.industries/api/mcp \
--header "Authorization: Bearer pc_live_your_key".vscode/mcp.json
{
"servers": {
"ephemeris": {
"type": "http",
"url": "https://ephemeris.cascade.industries/api/mcp",
"headers": {
"Authorization": "Bearer pc_live_your_key"
}
}
}
}~/.codex/config.toml, key read from an environment variable
[mcp_servers.ephemeris]
url = "https://ephemeris.cascade.industries/api/mcp"
bearer_token_env_var = "EPHEMERIS_API_KEY"~/.gemini/settings.json
{
"mcpServers": {
"ephemeris": {
"httpUrl": "https://ephemeris.cascade.industries/api/mcp",
"headers": {
"Authorization": "Bearer pc_live_your_key"
}
}
}
}claude_desktop_config.json, through the mcp-remote bridge
{
"mcpServers": {
"ephemeris": {
"command": "npx",
"args": [
"-y", "mcp-remote",
"https://ephemeris.cascade.industries/api/mcp",
"--header", "Authorization: Bearer pc_live_your_key"
]
}
}
}hosted MCP tool
"tools": [{
"type": "mcp",
"server_label": "ephemeris",
"server_url": "https://ephemeris.cascade.industries/api/mcp",
"headers": { "Authorization": "Bearer pc_live_your_key" }
}]MCP connector
"mcp_servers": [{
"type": "url",
"url": "https://ephemeris.cascade.industries/api/mcp",
"name": "ephemeris",
"authorization_token": "pc_live_your_key"
}]Streamable HTTP transport
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.
get_versionPublic, 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.
describe_forecastDeterministic 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.
plot_forecastRender 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.
forecastRuns 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.
list_modelsThe live model panel with prices and context caps.
get_balanceSpendable credits, excluding holds from in-flight forecasts.
get_usageNewest-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.
Millicredits
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.
“mc” means millicredits.
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.
Read model prices from GET /api/v1/models. History length has no billing multiplier.
Request guardrails
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.
Recovery
400The body, limits, mode, model, or pagination is invalid.
401The bearer API key is missing, invalid, or revoked.
402Top up using the returned topup_url, then retry.
409The key is in progress or was reused with a different body.
429Retry after the number of seconds in Retry-After.
503Pricing or the model service is unavailable.
Ready to forecast