Skip to content

API reference

Stored forecasts with confidence intervals

Forecasts are produced on a schedule from accumulated history, not computed on request. When none exists this returns 409 data_not_ready rather than a flat line.

GET/v1/forecasts
Request
curl "https://api.cresva.ai/v1/forecasts?type=revenue&brand_id=brd_8Kq2mR4xVn" \  -H "Authorization: Bearer $CRESVA_API_KEY"

Illustrative values. The parameter names, types and defaults are the ones the endpoint enforces.

Authorization

Authorization
Required. A bearer token: Authorization: Bearer cresva_sk_live_.... A key beginning cresva_sk_test_ returns simulated data from this endpoint instead.

Query parameters

Sent in the query string. Values are coerced to the types below, so numbers may be sent as strings.

  • typeenumrequired
    One ofrevenuecacroasconversionscustom
  • horizon_daysintegeroptionaldefault 30

    min 7 · max 365

  • include_confidenceenumoptionaldefault "true"
    One oftruefalse
  • metricstringoptional

    Metric name when type is `custom`.

  • brand_idstringoptional

    Brand to query. Required when the account has more than one brand.

When brand_id is required

It is optional in the schema and required in practice as soon as a key can reach more than one brand. A key scoped to a single brand, or an account that has one, can leave it out. Call /v1/brands to see which ids a key can address.

Response

Returns 200 with the fields below. Every successful response also carries meta.request_id, which identifies the call in a support conversation, and meta.simulated, which is true when a test key was used.

  • typestringrequired
  • horizon_daysnumberrequired
  • granularitystringrequired
  • pointsarray of objectrequired
    • datestringrequired
    • predicted_valuenumber or nullrequired
    • confidence_intervalobjectoptional
      • lownumber or nullrequired
      • highnumber or nullrequired
  • factorsarray of objectrequired
  • accuracyobjectrequired
    • mapenumber or nullrequired
    • modelstringrequired
  • metaobjectrequired

    Present on every successful response.

    • request_idstringrequired
    • simulatedbooleanrequired

      True when a cresva_sk_test_ key was used and the data is simulated.

200
{  "type": "string",  "horizon_days": 30,  "granularity": "day",  "points": [    {      "date": "2026-07-15",      "predicted_value": 51204,      "confidence_interval": {        "low": 46980,        "high": 55428      }    }  ],  "factors": [    {      "...": "provider shaped"    }  ],  "accuracy": {    "mape": 0.08,    "model": "prophet"  },  "meta": {    "request_id": "req_01JQ8Z3M6WT4",    "simulated": false  }}

Shape generated from the response schema. The values are illustrative.

Errors

Failures use one envelope: { "error": { "code", "message" } }. The codes this endpoint can return:

400 invalid_request
A parameter failed the schema: wrong type, out of range, or an enum value that does not exist. The message names the field.
401 unauthorized
No Authorization header, a malformed one, or a key that has been revoked or has expired.
403 forbidden
The key is valid but is not scoped to the brand in the request. Keys can be narrowed to one brand.
429 rate_limited
The per-minute quota for this key is spent. Retry-After and error.retry_after both carry the seconds to wait.
409 data_not_ready
The request was well formed and authorised, and there is no ingested data to answer it yet. A 500 would say we broke and a 200 of zeroes would be a lie, so this is its own status.
500 internal_error
Something failed on our side. The request_id identifies the call.