Ephemeris Time-Series Forecasting

Forecast, predict or project one or more numeric time series (sales, demand, traffic, load, prices, metrics, sensor data) with prediction intervals, using Ephemeris' panel of zero-shot foundation models. Mode ensemble is the most accurate: it is level with the top of the TIME benchmark and scores better on GIFT-Eval than any single model in the panel. Returns structured JSON: `forecasts` (one entry per input series, quantile-keyed arrays) and `meta` with the request id, models used, the served weight revision per model, and the credits charged and remaining. Spends credits on every successful call.

{
  "type": "object",
  "properties": {
    "mode": {
      "type": "string",
      "enum": [
        "route",
        "ensemble",
        "explicit"
      ],
      "description": "\"route\": Ephemeris picks the best model for the data, falling back to a small ensemble if it fails. \"ensemble\": run all compatible models and blend them; best calibration, highest cost. \"explicit\": run the single model named in `model`."
    },
    "model": {
      "description": "Required when mode is \"explicit\". Must be a name returned by list_models.",
      "type": "string",
      "minLength": 1
    },
    "series": {
      "minItems": 1,
      "maxItems": 64,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "values": {
            "anyOf": [
              {
                "minItems": 1,
                "type": "array",
                "items": {
                  "type": "number"
                }
              },
              {
                "minItems": 1,
                "type": "array",
                "items": {
                  "minItems": 1,
                  "type": "array",
                  "items": {
                    "type": "number"
                  }
                }
              }
            ],
            "description": "Observed history, oldest first. A flat number array is one univariate series. A nested array is one multivariate series with one inner array per variate, all the same length."
          },
          "freq": {
            "description": "Pandas-style sampling frequency such as \"H\", \"D\", \"W\", \"15min\" or \"M\". Improves routing and seasonal handling; omit if unknown.",
            "type": "string",
            "minLength": 1
          },
          "covariates": {
            "type": "object",
            "properties": {
              "past": {
                "type": "object",
                "propertyNames": {
                  "type": "string"
                },
                "additionalProperties": {
                  "type": "array",
                  "items": {
                    "type": "number"
                  }
                },
                "description": "Named historical channels, each the same length as the series context."
              },
              "future": {
                "description": "Known-future channels, each exactly `horizon` long. Every future channel must also appear in `past`.",
                "type": "object",
                "propertyNames": {
                  "type": "string"
                },
                "additionalProperties": {
                  "type": "array",
                  "items": {
                    "type": "number"
                  }
                }
              }
            },
            "required": [
              "past"
            ],
            "description": "Optional exogenous covariates. Only models with `covariates: true` in list_models can use them. In route and ensemble mode the panel narrows to those models; in explicit mode, naming a model without covariate support is an error."
          }
        },
        "required": [
          "values"
        ]
      },
      "description": "One to 64 series forecast in one request. All share horizon and quantiles."
    },
    "horizon": {
      "description": "Number of future steps to forecast, 1 to 4096. Defaults to 64. Some models stop short of this (max_horizon in list_models): route and ensemble skip them, explicit mode rejects the request.",
      "type": "integer",
      "minimum": 1,
      "maximum": 4096
    },
    "context_len": {
      "description": "Most recent points per variate to feed the model and bill for, 1 to 16384. Defaults to 256. Values beyond the model's context cap are truncated at the cap.",
      "type": "integer",
      "minimum": 1,
      "maximum": 16384
    },
    "quantiles": {
      "description": "Up to 21 quantile levels strictly between 0 and 1, for example [0.1, 0.5, 0.9]. The response keys forecasts by these as decimal strings.",
      "maxItems": 21,
      "type": "array",
      "items": {
        "type": "number",
        "exclusiveMinimum": 0,
        "exclusiveMaximum": 1
      }
    },
    "top_k": {
      "description": "Ensemble only: cap on how many models participate.",
      "type": "integer",
      "minimum": 1,
      "maximum": 16
    },
    "combine": {
      "description": "Ensemble only. \"mixture\" averages the predictive distributions (default); \"vincentize\" averages the quantiles.",
      "type": "string",
      "enum": [
        "mixture",
        "vincentize"
      ]
    },
    "idempotency_key": {
      "description": "Client-chosen key, 8 to 128 characters of letters, numbers, dot, underscore, colon or hyphen. A retry with the same key and identical body replays the stored result without charging again.",
      "type": "string",
      "pattern": "^[A-Za-z0-9._:-]{8,128}$"
    }
  },
  "required": [
    "mode",
    "series"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "forecasts": {
      "description": "One entry per input series, aligned with the request.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "quantiles": {
            "description": "Forecast values keyed by quantile level as a decimal string (\"0.5\"). A flat array of numbers for a univariate series, one inner array per variate for a multivariate one, each `horizon` long. A null marks a value the model could not produce.",
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {
              "type": "array",
              "items": {}
            }
          }
        },
        "additionalProperties": {},
        "description": "One entry per input series, in request order."
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "gateway_request_id": {
          "description": "Ephemeris request id. Quote this in support requests and usage lookups.",
          "type": "string"
        },
        "request_id": {
          "description": "Upstream model-panel request id for the forecast.",
          "type": [
            "string",
            "null"
          ]
        },
        "upstream_request_ids": {
          "description": "All upstream ids when a mixed-frequency batch was split.",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "mode": {
          "type": "string"
        },
        "models_used": {
          "description": "Models whose output is in this forecast.",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "model_revisions": {
          "description": "Served weight revision (Hugging Face commit hash) per model in models_used. Identifies the exact weights, independent of this server's version.",
          "anyOf": [
            {
              "type": "object",
              "propertyNames": {
                "type": "string"
              },
              "additionalProperties": {
                "type": "string"
              }
            },
            {
              "type": "null"
            }
          ]
        },
        "router_confidence": {},
        "per_model_latency_ms": {},
        "notes": {},
        "billing": {
          "type": "object",
          "properties": {
            "settled_mc": {
              "description": "Millicredits charged for this call.",
              "type": "string"
            },
            "balance_mc": {
              "description": "Millicredits remaining after this call.",
              "type": "string"
            }
          },
          "additionalProperties": {}
        }
      },
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": {}
}

Discover the model panel: each model's availability right now (healthy), capabilities (multivariate, covariates, max_horizon, auto_max_horizon), its weight in an ensemble at each horizon, pinned and actually served weight revision, price per thousand series-slots in millicredits and maximum billable context. Call this before using forecast in explicit mode; the deployed panel can differ from any documentation.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "models": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "enabled": {
            "type": "boolean"
          },
          "healthy": {
            "description": "Whether the model's worker is up and accepting forecasts right now.",
            "type": "boolean"
          },
          "hf_repo": {
            "type": [
              "string",
              "null"
            ]
          },
          "revision": {
            "description": "Revision pinned in the panel manifest, if any.",
            "type": [
              "string",
              "null"
            ]
          },
          "served_revision": {
            "description": "Commit hash of the weights the worker actually loaded.",
            "type": [
              "string",
              "null"
            ]
          },
          "multivariate": {
            "type": "boolean"
          },
          "covariates": {
            "type": "boolean"
          },
          "pools": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "max_horizon": {
            "description": "Longest horizon this model can forecast; null means no limit.",
            "type": [
              "number",
              "null"
            ]
          },
          "auto_max_horizon": {
            "description": "Longest horizon at which route and ensemble use this model; null means no limit beyond max_horizon. Explicit mode may still name it up to max_horizon.",
            "type": [
              "number",
              "null"
            ]
          },
          "ensemble_weights": {
            "description": "Weight this model carries in a full-panel ensemble, keyed by horizon in steps. Absent at horizons past max_horizon or auto_max_horizon.",
            "anyOf": [
              {
                "type": "object",
                "propertyNames": {
                  "type": "string"
                },
                "additionalProperties": {
                  "type": "number"
                }
              },
              {
                "type": "null"
              }
            ]
          },
          "skill_weight": {
            "description": "Diagnostic feedback score. Not the ensemble's weighting; see ensemble_weights.",
            "type": [
              "number",
              "null"
            ]
          },
          "credits": {
            "type": [
              "number",
              "null"
            ]
          },
          "price_per_kslot_mc": {
            "description": "Millicredits per thousand series-slots; null when the model is not billable.",
            "type": [
              "string",
              "null"
            ]
          },
          "billing_context_cap": {
            "description": "Most context points billed per variate; longer inputs are billed at the cap.",
            "type": [
              "number",
              "null"
            ]
          },
          "detail": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "name"
        ],
        "additionalProperties": {}
      }
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": {}
}

Return the account's spendable credit balance in millicredits, excluding credits reserved by in-progress forecasts. 1000 millicredits equal one credit.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "balance_mc": {
      "description": "Spendable millicredits (ledger minus active holds).",
      "type": "string"
    },
    "active_holds_mc": {
      "description": "Millicredits reserved by in-flight forecasts.",
      "type": "string"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": {}
}

Return the account's forecast request log, newest first, with the mode, models used, series count, horizon, credits estimated and settled, HTTP status and latency of each request.

{
  "type": "object",
  "properties": {
    "limit": {
      "description": "Rows per page, 1 to 200. Defaults to 50.",
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    },
    "offset": {
      "description": "Rows to skip. Use `pagination.next_offset` from the previous page.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

{
  "type": "object",
  "properties": {
    "data": {
      "description": "Request log rows, newest first.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "requestId": {
            "type": "string"
          }
        },
        "additionalProperties": {}
      }
    },
    "limit": {
      "type": "number"
    },
    "offset": {
      "type": "number"
    },
    "pagination": {
      "type": "object",
      "properties": {
        "limit": {
          "type": "number"
        },
        "offset": {
          "type": "number"
        },
        "returned": {
          "type": "number"
        },
        "has_more": {
          "type": "boolean"
        },
        "next_offset": {
          "type": [
            "number",
            "null"
          ]
        }
      },
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": {}
}