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://your-domain.com/api/v1

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://your-domain.com/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

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

Reference

Endpoints

GET/api/v1/models

List models

Lists available models with their price and maximum billable context.

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.

GET/api/v1/usage

List usage

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

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.

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 points to bill for. Defaults to 256.
`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

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

{
  "forecast": {
    "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"],
    "billing": {
      "settled_mc": "12",
      "balance_mc": "4988"
    }
  }
}

Forecast values mirror the model response. Univariate entries return flat horizon arrays; multivariate entries return nested arrays. Quantile keys are decimal strings such as 0.5.

Millicredits

Pricing

Cost per model

price_per_kslot_mc × slots × ceil(context / 1024) × ceil(horizon / 64)

Each model is priced per series, per 1,024 context points, and per 64 forecast steps.

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 and maximum billable context from GET /models.

Request guardrails

Limits

Series64per request

Series slots256variates total

Context16,384points per variate

Horizon512forecast steps

Quantiles21per request

JSON body10 MBmaximum

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

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.

Open dashboard Download OpenAPI