/api/auth/forecast-requests
Request a new Quotient forecast for a market or question
Ask Quotient to research and publish a new forecast. Two kinds of request: venue_market targets one exact live binary market on a covered venue — polymarket, polymarket_us, kalshi, or limitless — by its venue-native market_id, and is also how you refresh a market Quotient already covers; question is your own free-text question with resolution rules and an end date. Resolve Kalshi event tickers and Polymarket URLs or slugs through free GET /api/public/forecast-targets, then submit one returned child identity: a Kalshi child ticker or numeric Polymarket Gamma market id. Polymarket ids are validated against Gamma before admission: unknown or non-numeric ids return 422 venue_market_not_found and closed or archived markets return 422 venue_market_closed, in both cases before any payment settles. Generation costs $1.00 (1,000 credits). Stored forecasts cost $0.01 on GET /api/v1/markets/{slug}/forecast. Use free /api/public/forecast-availability to check whether a stored forecast is available before requesting generation. The forecast is generated in the background: you get 202 with a jobId immediately, then poll GET /api/auth/forecast-requests/{jobId} until it finishes. User-requested forecast generation has no minimum resolution lead time and does not apply volume, liquidity, or activity selection floors: a question with a future end_date, or a supported venue contract that is still active, remains eligible even when less than 24 hours remain; contract-validity and topic-scope checks still apply. Every request runs Quotient's standard production pipeline with server-managed pricing, snapshots, models, workers, research providers, and publication settings. Limitless markets can be requested on demand even outside the scheduled top-five lane. Sports outcomes, mention markets, and short-horizon crypto up/down markets (fifteen-minute and hourly settles; daily-close and longer crypto horizons remain requestable) are excluded from forecasting: they are rejected up front with 422 forecast_topic_excluded and consume no quota or payment, whether given as a tracked venue market or a free-text question.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| Idempotency-Key | header, required | string | Minimum length: 1; Maximum length: 128 |
Request body
application/json, required
| Field | Type | Description | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Alternative 1 | VenueMarketForecastRequest | Exactly one alternative Alternative 1 fields
| |||||||||||||||||||||
| Alternative 2 | QuestionForecastRequest | Exactly one alternative Alternative 2 fields
|
Responses
202: Accepted; Location points to the owner-scoped status URL
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| jobId required | string | Format: uuid | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| status required | "accepted" | "submitted" | "running" | "succeeded" | "rejected" | "failed" | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| createdAt required | string | Format: date-time | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| updatedAt required | string | Format: date-time | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| forecastIds required | string[] | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| forecasts required | ForecastRequestForecast[] | Published forecast outputs. Empty while pending or when execution fails.forecasts fields
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| errorCode required | string | null | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| listing required | CanonicalMarketRouting | null | listing fields
|
401: Invalid or missing Quotient API key
402: Payment Required
| Field | Type | Description |
|---|---|---|
| error required | string | Error code |
| message required | string | Human-readable message |
| retry_after | integer | Seconds to wait (only on 429) |
| retryAfter | integer | Seconds to wait for owner-scoped forecast-request quota errors. |
| limit_scope | string | Quota scope that rejected the request, such as standard or x_research. |
| quotaScope | string | Stable forecast-request quota scope, such as venue_market_daily. |
| limit | integer | Configured bound for the forecast-request quota that was exceeded. |
403: Account lacks an active Quotient API entitlement
409: Idempotency key payload conflict
422: Strict validation failed, the Kalshi identifier names an event rather than one child market (venue_event_requires_market), the market does not exist or the Polymarket id is not the numeric Gamma id (venue_market_not_found), the Polymarket market is closed or archived (venue_market_closed), or the subject is excluded (forecast_topic_excluded)
| Field | Type | Description |
|---|---|---|
| error required | string | Error code |
| message required | string | Human-readable message |
| retry_after | integer | Seconds to wait (only on 429) |
| retryAfter | integer | Seconds to wait for owner-scoped forecast-request quota errors. |
| limit_scope | string | Quota scope that rejected the request, such as standard or x_research. |
| quotaScope | string | Stable forecast-request quota scope, such as venue_market_daily. |
| limit | integer | Configured bound for the forecast-request quota that was exceeded. |
429: The caller exceeded a per-second, per-minute, daily, or concurrency limit. No credits are debited and no x402 payment is settled for this response.
| Field | Type | Description |
|---|---|---|
| error required | string | Error code |
| message required | string | Human-readable message |
| retry_after | integer | Seconds to wait (only on 429) |
| retryAfter | integer | Seconds to wait for owner-scoped forecast-request quota errors. |
| limit_scope | string | Quota scope that rejected the request, such as standard or x_research. |
| quotaScope | string | Stable forecast-request quota scope, such as venue_market_daily. |
| limit | integer | Configured bound for the forecast-request quota that was exceeded. |
Set QUOTIENT_API_KEY in your shell and replace example identifiers with returned IDs before running a request.
curl --request POST \
--header "x-quotient-api-key: $QUOTIENT_API_KEY" \
--header 'Idempotency-Key: example-idempotency-key' \
--header "content-type: application/json" \
--data '{"kind":"venue_market","venue":"polymarket","market_id":"example"}' \
'https://quotient-api-gateway.onrender.com/api/auth/forecast-requests'{
"jobId": "example",
"status": "accepted",
"createdAt": "2027-01-01T00:00:00Z",
"updatedAt": "2027-01-01T00:00:00Z",
"forecastIds": [
"example"
],
"forecasts": [
{
"id": "example",
"question": "example",
"probability": 0,
"createdAt": "2027-01-01T00:00:00Z",
"headline": "example",
"bluf": "example",
"thesis": "example",
"reasoningSummary": "example",
"citationCount": 0,
"relationships": {
"assets": [
{
"relationship": null,
"direction": null,
"via": null,
"id": null,
"assetKey": null,
"name": null,
"ticker": null,
"asset_type": null
}
],
"markets": [
{
"relationship": null,
"direction": null,
"via": null,
"marketKey": null,
"venue": null,
"nativeMarketId": null,
"question": null
}
],
"signals": [
{
"relationship": null,
"direction": null,
"via": null,
"id": null,
"signal_type": null,
"canonical_endpoint": null,
"side": null,
"published_at": null
}
],
"truncated": {
"assets": false,
"markets": false,
"signals": false
}
}
}
],
"errorCode": "example",
"listing": {
"venue": "polymarket",
"nativeMarketId": "example",
"nativeEventId": "example",
"seriesTicker": "example",
"marketKey": "example",
"quotientMarketId": "example",
"slug": "example",
"marketUrl": "example",
"sourceUrl": "example",
"broker_channels": [
"robinhood"
],
"robinhood_category": "example",
"robinhood_url": "example"
}
}