---
title: "Rank driver datasets for your timeseries"
method: POST
path: "/api/v1/drivers"
---

# Rank driver datasets for your timeseries

`POST /api/v1/drivers`

Retrieves drivers ranked by how well they explain your timeseries, returning
a scored list of potential economic drivers. Results are ordered by relevance
score descending.

This is a synchronous billed endpoint — you are charged per driver returned.
No charge is recorded on validation errors or upstream failures.

## Request body

- RecommendRequestV1 — Body of `POST /api/v1/drivers`. Mirrors the upstream Recommend service contract. Note that the version field is named `version` (not `pipeline_version` as on `/forecasts`). Required fields: `version`, `recency_factor`, `timeseries_metadata`. Both `filters` and `timeseries` are optional — when omitted, the handler drops them from the upstream payload entirely (no `null` is sent). When `filters.limit` is omitted, a per-environment default is applied.
  - `filters` Filters — Optional narrowing for forecast, drivers, and alerts requests. Category and region ids must fall in **1–9999**. Discover valid ids via `GET /api/v1/regions` and `GET /api/v1/categories` — submitted ids are not cross-checked on submit.
    - `categories` integer[] — Thematic category ids to filter by; each must be an integer **1–9999** inclusive.
    - `general_drivers` boolean — When true, general (non category/region-specific) drivers are included in the driver candidate pool. Defaults to false.
    - `limit` integer — Maximum number of items to return. When omitted, a per-environment default is applied (100 by default). The maximum accepted value is operator-configurable (default 1000).
    - `regions` integer[] — Geographic region ids to filter by; each must be an integer **1–9999** inclusive.
  - `recency_factor` number, double, required — Weight given to more recent observations when ranking drivers. 0.0 = equal weight; 1.0 = strongest recency bias.
  - `timeseries` object — Optional. Map of YYYY-MM-DD date keys to numeric observation values. When supplied, all keys must parse as YYYY-MM-DD and all values must be finite. Unlike `/forecasts`, this endpoint is frequency-agnostic — no monthly alignment, gap detection, or minimum length is enforced. When omitted, the handler does not forward the field upstream.
  - `timeseries_metadata` TimeseriesMetadata, required — Descriptive metadata the ranking model uses to interpret and contextualize the timeseries.
    - `description` string — Extended context for the model, up to 2048 characters. More detail improves driver relevance.
    - `keywords` string[] — Up to 20 semantic tags that help anchor the search to relevant datasets.
    - `title` string, required — Short identifier for the series, 20–511 characters.
  - `version` 'v1', required — Recommend pipeline version. Closed set; only `v1` is supported today. Used locally to select the per-version validator and is **not forwarded** to the upstream Recommend service.

## Response `200`

Ranked driver candidates for your timeseries.

- object
  - `data` object
    - `drivers` DriverItemV1[]
      - `driver_name` string — Human-readable name of the dataset.
      - `hash_id` string — Stable identifier for the dataset; use to reference this driver across requests.
      - `score` number, double — Relevance score indicating how well this dataset explains your timeseries (higher is more relevant).
  - `message` string
  - `status` integer

## Other responses

- `400` — Malformed JSON body.
- `401` — Missing or invalid bearer token.
- `402` — Insufficient credits — the request did not reach the upstream service.
- `413` — Request body too large.
- `422` — Payload failed validation.
- `429` — Rate limit exceeded — too many synchronous billed requests per minute.
- `502` — Upstream service error or unreachable.
- `503` — Service Unavailable

---

[API](https://skmtc.net/sybilion/apis/sybilion-api.md) · [All operations](https://skmtc.net/sybilion/apis/sybilion-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sybilion/sybilion-api/versions/2ba1f4c6f25d/schema)