Skip to content
SpectralBotSpectralBot API

Settled contest history for a series

GET
/v1/contests
curl --request GET \
  --url 'https://api.cotes.ai/v1/contests?series=KXBTC15M&limit=20' \
  --header 'Authorization: Bearer <token>'

Settled rounds for a series prefix (e.g. KXBTC15M), newest first, each with all Cotes AI signals and their graded outcomes. This is the endpoint for “how did the signals actually do” — live rounds are excluded, since their signals are still pending.

since and before window on window.expires_at, which for a 15-minute round is its settlement time. before is inclusive, so paginate by passing the oldest expires_at you received and discarding the repeated first row.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
series
required
string
>= 1 characters

Series prefix, e.g. KXBTC15M. Match is exact and case-sensitive on the prefix. A full ticker also resolves while that round is live, but use /v1/contests/{ticker} for a specific round.

Example
KXBTC15M
limit
integer
default: 20 >= 1 <= 100

Maximum rounds to return, newest first.

since
string format: date-time

Only rounds settling at or after this instant (ISO 8601).

before
string format: date-time

Only rounds settling at or before this instant (ISO 8601), inclusive.

Responses

Section titled “Responses”

200

Section titled “200”

Settled contests, newest first. Empty when the series has none.

Media typeapplication/json
object
contests
required
Array<object>
object
ticker
required
string
state
required
string
Allowed values: live expired settled
window
required
object
opens_at
required
string format: date-time
expires_at
required
string format: date-time
strike_price_dollars

Strike / to-beat underlying price in USD, if known.

number | null
settled_side
string | null
Allowed values: up down
settled_price_dollars

Oracle settled underlying price (expiration value) in USD once the contest is settled; null while live or if the oracle did not report it.

number | null
signals
required

All Cotes AI signals for this contest (consumers apply their own thresholds).

Array<object>
object
ticker
required

Contest ticker this signal belongs to (same as parent Contest.ticker).

string
raised_at
required
string format: date-time
side
required
string
Allowed values: up down
confidence
required

Model probability on side (0–100).

number
entry_price_cents
required

Venue quote for side on the 0–100¢ scale ($0.54 → 54). Same denomination as edge_cents.

number
edge_cents
required

Confidence − entry_price_cents. Signed probability points, not settlement money.

number
outcome
required
string
Allowed values: pending win loss void
model_version

Version tag of the model that produced this reading. Stable across a model’s life and changes only when a new model is deployed, so it groups readings by the model behind them. Null on readings stored before the tag was recorded.

string | null
Example
{
  "contests": [
    {
      "state": "live",
      "settled_side": "up",
      "signals": [
        {
          "side": "up",
          "outcome": "pending",
          "model_version": "c5456da6"
        }
      ]
    }
  ]
}

401

Section titled “401”

Missing or invalid API key

Media typeapplication/problem+json
object
type
required
string format: uri
title
required
string
status
required
integer
detail
required
string
Examplegenerated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example"
}

422

Section titled “422”

Invalid query parameter (e.g. limit out of range).

429

Section titled “429”

Too many requests

Media typeapplication/problem+json
object
type
required
string format: uri
title
required
string
status
required
integer
detail
required
string
Examplegenerated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example"
}

Headers

Section titled “Headers”
Retry-After
integer
X-RateLimit-Limit
integer
X-RateLimit-Remaining
integer