Skip to content

Settled contest history for a series

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

Settled rounds for a series prefix (e.g. KXBTC15M or KXETH15M), 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.

series
required
string
>= 1 characters

Series prefix: KXBTC15M, KXETH15M, KXSOL15M or KXXRP15M (GET /v1/series lists them). 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.

fired_only
boolean

When true, each round’s signals lists only the readings with fired: true instead of every reading. A settled round carries a reading every few seconds, so this cuts the response to SpectralEdge’s own calls. Leave it false to apply your own thresholds.

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

Media typeapplication/json
object
contests
required
Array<object>
object
ticker
required
string
series
required

Series prefix of the ticker, as passed in the series query parameter.

string
asset
required

The underlying asset this contest is on: BTC, ETH, SOL or XRP for the catalog series. A recorded series outside the catalog reports its own asset, such as GOLD for KXGOLD15M.

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 price of the contest’s own asset in USD, if known. The scale follows the asset: tens of thousands for BTC, a few dollars with fractions of a cent for XRP.

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
fired

Whether SpectralEdge showed this reading as a signal: it cleared the platform’s confidence, edge and distance-from-strike thresholds in force when it was raised. Readings that did not fire are still listed.

boolean
Example
{
"contests": [
{
"series": "KXBTC15M",
"asset": "BTC",
"state": "live",
"settled_side": "up",
"signals": [
{
"side": "up",
"outcome": "pending",
"model_version": "c5456da6"
}
]
}
]
}

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"
}

The key is valid, but the account’s trial or subscription does not grant access: it has lapsed, or a live trial needs a card. Problem type payment-required. Not retryable until the account is renewed at https://app.cotes.ai.

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"
}

The client IP address is blocked. Problem type forbidden. Returned before the key is checked, and not retryable.

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"
}

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

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"
}
Retry-After
integer
X-RateLimit-Limit
integer
X-RateLimit-Remaining
integer