POST /api/v1/drivers
Synchronous endpoint that validates the body, runs the drivers / signal recommendations engine, and returns the response verbatim.
| Attribute | Details |
|---|---|
| Auth | Required |
| Billing | Charged only on 2xx. Cost scales with the number of results returned (see Pricing). |
Request (RecommendRequestV1)
| Field | Rules |
|---|---|
version | Must be "v1". Used only to pick the validator — stripped before the upstream call. |
recency_factor | 0.0–1.0. |
timeseries_metadata | Same title/description/keywords rules as forecasts (title 20–511 bytes, etc.). |
filters | Optional — same JSON shape and validation as forecast filters. For browsing ids see Regions & categories; values are not cross-checked on submit. |
timeseries | Optional. If present: valid YYYY-MM-DD keys, finite values. Frequency-agnostic (no monthly grid / minimum length like forecasts). If omitted, not sent upstream. |
Typical responses
| Code | Meaning |
|---|---|
200 | Upstream success; body passed through. |
400 | Malformed JSON. |
402 | Insufficient available balance — no upstream call. Body: {"error":"insufficient credits"} or a variant with amounts — compare with available_eur_cents on GET /api/v1/me. |
422 | Validation failure — standard JSON envelope with error and details array. |
413 | Request body exceeds the maximum allowed size for this route. |
429 | Rate limited (per-user). |
502 | Transport error from the drivers engine. |
503 | Drivers feature not enabled for your account. |
Non-2xx responses are not charged (except your client retry logic). Repeating the same request with a stable X-Request-ID may deduplicate billing on success.
Pricing
Billing is per successful response (2xx): cost scales with how many result items are returned, plus a fixed base fee. The exact rate is shown on the Developers Portal pricing page.
A pre-charge check runs before the call. It assumes the worst case — as many billed items as filters.limit allows (default 1000 when omitted) — and returns 402 if available_eur_cents on GET /api/v1/me cannot cover that ceiling. The settled charge uses the actual item count returned, which may be lower.