---
title: "Search instruments"
method: GET
path: "/instruments/search"
tags: ["Markets"]
---

# Search instruments

`GET /instruments/search`

## Request

- Base URL: `https://arena-predictions.com/api/v1`
- URL: `https://arena-predictions.com/api/v1/instruments/search`
- Auth: HTTP bearer

A bet in words ("chiefs ml", "kc -3.5", "kc mia under 44.5") to ranked instruments, through the same resolver as /ticker. Each result says which side of the instrument the words asked for.

## Query parameters

- `q` string, required
- `league` string
- `limit` integer

## Response `200`

Ranked results.

- InstrumentSearch
  - `query` string, required
  - `count` integer, required
  - `results` object[], required
    - `rank` integer, required: 1 is the earliest game.
    - `querySide` 'yes' | 'no', required: The side of the instrument the words asked for.
    - `queryLabel` string, required: That side in the query's own terms: MIA +3.5.
    - `queryMeans` string, required
    - `instrument` Instrument, required
      - `id` string, required: Arena's permanent id. Opaque.
      - `slug` string, nullable, required: Readable alias. May change.
      - `gameId` string, nullable, required
      - `gameSlug` string, nullable
      - `league` string, nullable, required
      - `marketType` 'moneyline' | 'spread' | 'total' | 'null', nullable, required
      - `period` string, nullable, required: FG is the full game.
      - `stat` string, nullable
      - `line` number, nullable, required
      - `subject` object, nullable, required
        - `code` string, nullable, required
        - `name` string, nullable, required
      - `label` string, nullable, required: The YES side in words: KC ML, KC -3.5, Over 44.5.
      - `oppositeLabel` string, nullable, required: The NO side in words.
      - `yesMeans` string, nullable, required: What YES pays on, in a sentence.
      - `startsAt` string, date-time, nullable, required: Scheduled start. Postponements move it; the id never moves.
      - `gameStatus` string, nullable, required
      - `home` object, required
        - `code` string, nullable, required
        - `name` string, nullable, required
      - `away` object, required
        - `code` string, nullable, required
        - `name` string, nullable, required
      - `pushPossible` boolean, required
      - `tieRule` string, nullable
      - `settlesOn` string, nullable
      - `postponementWindowHours` number, nullable
      - `rulesVersion` integer, nullable
      - `venues` string[], required: Venues with a listing Arena shows.
      - `listings` VenueListing[]: Only on GET /instruments/{ref}.
        - `venue` 'kalshi' | 'novig' | 'polymarket', required
        - `polarity` 1 | -1, required: 1: holding the listed side pays when the instrument is YES. -1: when it is NO.
        - `sideLabel` string, nullable, required: The listed side in Arena's words.
        - `fungibility` 'exact' | 'condition_scope', required
        - `reviewed` boolean, required: True when a person approved the match; false when it was matched by rule.
        - `note` string, nullable, required: How the venue's contract differs, in plain words.
        - `buyForYes` string, nullable, required: Kalshi: yes or no, the side of the listed market to buy to hold the instrument's YES. Other venues: only while the venue-data switch is on.
        - `buyForNo` string, nullable, required
        - `venueMarketId` string, nullable: Only while the venue-data switch is on.
        - `venueSideRef` string, nullable: Only while the venue-data switch is on.
        - `venueEvent` string, nullable: Only while the venue-data switch is on.

## Other responses

- `400`: invalid_request: q is empty or over 200 characters, or a bad league or limit.
- `401`: Missing, malformed, unknown, revoked or expired key. Carries a WWW-Authenticate: Bearer challenge.
- `403`: insufficient_scope: the key does not carry markets:read.
- `429`: rate_limited (over the plan's minute limit) or quota_exceeded (over the month). Only while the limits are enforced; until then requests are counted and the headers set, and nothing is refused. error.retryAfterSeconds equals Retry-After.
- `503`: The key could not be verified, or the data could not be read, right now. Retry after the Retry-After seconds.

---

[API](https://skmtc.dev/arena-predictions/apis/arena-api.md) · [All operations](https://skmtc.dev/arena-predictions/apis/arena-api/llms.txt) · [OpenAPI document](https://skmtc.dev/arena-predictions/apis/arena-api/revisions/9d89d166dae6?raw)