Skip to main content
GET
Search contracts, events or base events

Overview

Search runs over a single index of event contracts. The type parameter picks the level hits come back at, and the response echoes it in data.type so a client can branch on the shape it actually received.

Filters apply to contracts

This matters when type is events or base-events: an event or base event is only found through its matching contracts. One whose contracts are all filtered out — for example an event holding only DELETED contracts under the default state — is not returned at all, even if its own text matches the query. found, page, and perPage count whatever type returns, not the underlying contracts. contractsFound on each hit is the count of every matching contract under it, which can exceed the number of contracts attached to the hit.

Query syntax

q searches symbols, contract questions, event names, and base-event specifications. Symbols are split on _, -, and ., so a partial query finds the full symbol:
Omit q entirely to browse the catalogue, ordered by soonest last-trade date first.

Parameters

Search results trail the catalogue

The index is updated from the catalogue and lags it by seconds. Treat a hit’s symbol as the key into Get Event Contracts and read anything that must be current — state, tradable — from there. Do not act on a hit’s own tradable field.

Response

Examples

Find contracts by text

Group hits by event, with more contracts each

Browse a single base event, tradable only

Include deleted contracts

Errors

  • 400 — an unknown type, or a parameter that failed validation
  • 502 — the search index was unavailable

Query Parameters

type
enum<string>
default:contracts

Level hits come back at. contracts (default) returns matching contracts; events returns one hit per event and base-events one per base event, each ranked by its best-matching contract and carrying up to contractsPerHit of them. Echoed in the response.

Available options:
contracts,
events,
base-events
q
string

Full-text query over symbols, questions, event names and base-event specifications. Symbols split on _, - and . so BPM 0822 finds BPM_0822_1750. Omit to browse, soonest last-trade date first.

Example:

"unemployment june"

state
string

Contract state. Omitted means ACTIVE; * matches every state, including DELETED.

Example:

"ACTIVE"

baseEventId
string

Only contracts under this base event.

Example:

"UNR"

eventId
string

Only contracts under this event.

Example:

"UNR_0822"

tradable
boolean

Only tradable (true) or non-tradable (false) contracts.

page
integer

1-based page number; 0 or omitted means 1.

Required range: x >= 0
Example:

1

perPage
integer

Hits per page, counting whatever type returns; 0 or omitted means 20, values above 100 are clamped to 100.

Required range: 0 <= x <= 100
Example:

20

contractsPerHit
integer

With type=events or type=base-events: matching contracts attached to each hit; 0 or omitted means 3, values above 99 are clamped to 99. Ignored for contracts.

Required range: 0 <= x <= 99
Example:

3

Response

One page of hits; data.type says which shape they are

Standard success envelope used by all success responses. data is endpoint-specific.

success
boolean
required
Example:

true

data
object

One page of contracts.