Search Prediction Market

Python (SDK)

from finance_dev import FinanceDev, models

with FinanceDev() as fd_client:

    res = fd_client.predictions.markets.search(type_=models.SearchType.CONTRACTS, q="unemployment june", state="ACTIVE", base_event_id="UNR", event_id="UNR_0822", category="Elections > United States House", page=1, per_page=20)

    while res is not None:
        # Handle items

        res = res.next()

import { FinanceDev } from "@ariesdotcom/finance-dev";

const financeDev = new FinanceDev();

async function run() {
  const result = await financeDev.predictions.markets.search({
    q: "unemployment june",
    state: "ACTIVE",
    baseEventId: "UNR",
    eventId: "UNR_0822",
    category: "Elections > United States House",
    page: 1,
    perPage: 20,
  });

  for await (const page of result) {
    console.log(page);
  }
}

run();

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.aries.com/v1/predictions/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.aries.com/v1/predictions/search"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.aries.com/v1/predictions/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "data": {
    "found": 1110,
    "hits": [
      {
        "baseEventId": "HORC",
        "contracts": [
          {
            "baseEventId": "HORC",
            "evaluationType": "==",
            "eventDisplayName": "US House of Representatives Control November 2026",
            "eventId": "HORC_1126",
            "eventQuestion": "Will the Republican Party win a majority in the United States House of Representatives in the 2026 general election?",
            "expirationDate": "2027-01-04T00:00:00Z",
            "lastTradeDate": "2027-01-04T00:00:00Z",
            "openInterest": 1309471,
            "question": "Will the Republican Party win a majority in the United States House of Representatives in the 2026 general election?",
            "startDate": "2025-04-02T00:00:00Z",
            "state": "ACTIVE",
            "strikeValue": "Republican",
            "symbol": "HORC_1126_Republican",
            "symbolSubTypes": [
              "YES",
              "NO"
            ],
            "tickSize": "0.01",
            "timeSpecifier": "2026.11",
            "tradable": true,
            "underlyingSpec": "The underlying is the political party whose members control at least 218 seats in the US House of Representatives on January 3rd of the year following a Congressional election. The list of US Representatives at the convening of each Congress is published January 4th on Congress.gov."
          },
          {
            "baseEventId": "HORC",
            "evaluationType": "==",
            "eventDisplayName": "US House of Representatives Control November 2026",
            "eventId": "HORC_1126",
            "eventQuestion": "Will the Republican Party win a majority in the United States House of Representatives in the 2026 general election?",
            "expirationDate": "2027-01-04T00:00:00Z",
            "lastTradeDate": "2027-01-04T00:00:00Z",
            "openInterest": 1204730,
            "question": "Will the Democratic Party win a majority in the United States House of Representatives in the 2026 general election?",
            "startDate": "2024-11-27T00:00:00Z",
            "state": "ACTIVE",
            "strikeValue": "Democratic",
            "symbol": "HORC_1126_Democratic",
            "symbolSubTypes": [
              "YES",
              "NO"
            ],
            "tickSize": "0.01",
            "timeSpecifier": "2026.11",
            "tradable": true,
            "underlyingSpec": "The underlying is the political party whose members control at least 218 seats in the US House of Representatives on January 3rd of the year following a Congressional election. The list of US Representatives at the convening of each Congress is published January 4th on Congress.gov."
          }
        ],
        "contractsFound": 3,
        "openInterest": 2514201,
        "underlyingSpec": "The underlying is the political party whose members control at least 218 seats in the US House of Representatives on January 3rd of the year following a Congressional election. The list of US Representatives at the convening of each Congress is published January 4th on Congress.gov."
      }
    ],
    "page": 1,
    "perPage": 1,
    "type": "base-events"
  },
  "success": true
}

GET

predictions

Python (SDK)

from finance_dev import FinanceDev, models

with FinanceDev() as fd_client:

    res = fd_client.predictions.markets.search(type_=models.SearchType.CONTRACTS, q="unemployment june", state="ACTIVE", base_event_id="UNR", event_id="UNR_0822", category="Elections > United States House", page=1, per_page=20)

    while res is not None:
        # Handle items

        res = res.next()

import { FinanceDev } from "@ariesdotcom/finance-dev";

const financeDev = new FinanceDev();

async function run() {
  const result = await financeDev.predictions.markets.search({
    q: "unemployment june",
    state: "ACTIVE",
    baseEventId: "UNR",
    eventId: "UNR_0822",
    category: "Elections > United States House",
    page: 1,
    perPage: 20,
  });

  for await (const page of result) {
    console.log(page);
  }
}

run();

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.aries.com/v1/predictions/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.aries.com/v1/predictions/search"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.aries.com/v1/predictions/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "data": {
    "found": 1110,
    "hits": [
      {
        "baseEventId": "HORC",
        "contracts": [
          {
            "baseEventId": "HORC",
            "evaluationType": "==",
            "eventDisplayName": "US House of Representatives Control November 2026",
            "eventId": "HORC_1126",
            "eventQuestion": "Will the Republican Party win a majority in the United States House of Representatives in the 2026 general election?",
            "expirationDate": "2027-01-04T00:00:00Z",
            "lastTradeDate": "2027-01-04T00:00:00Z",
            "openInterest": 1309471,
            "question": "Will the Republican Party win a majority in the United States House of Representatives in the 2026 general election?",
            "startDate": "2025-04-02T00:00:00Z",
            "state": "ACTIVE",
            "strikeValue": "Republican",
            "symbol": "HORC_1126_Republican",
            "symbolSubTypes": [
              "YES",
              "NO"
            ],
            "tickSize": "0.01",
            "timeSpecifier": "2026.11",
            "tradable": true,
            "underlyingSpec": "The underlying is the political party whose members control at least 218 seats in the US House of Representatives on January 3rd of the year following a Congressional election. The list of US Representatives at the convening of each Congress is published January 4th on Congress.gov."
          },
          {
            "baseEventId": "HORC",
            "evaluationType": "==",
            "eventDisplayName": "US House of Representatives Control November 2026",
            "eventId": "HORC_1126",
            "eventQuestion": "Will the Republican Party win a majority in the United States House of Representatives in the 2026 general election?",
            "expirationDate": "2027-01-04T00:00:00Z",
            "lastTradeDate": "2027-01-04T00:00:00Z",
            "openInterest": 1204730,
            "question": "Will the Democratic Party win a majority in the United States House of Representatives in the 2026 general election?",
            "startDate": "2024-11-27T00:00:00Z",
            "state": "ACTIVE",
            "strikeValue": "Democratic",
            "symbol": "HORC_1126_Democratic",
            "symbolSubTypes": [
              "YES",
              "NO"
            ],
            "tickSize": "0.01",
            "timeSpecifier": "2026.11",
            "tradable": true,
            "underlyingSpec": "The underlying is the political party whose members control at least 218 seats in the US House of Representatives on January 3rd of the year following a Congressional election. The list of US Representatives at the convening of each Congress is published January 4th on Congress.gov."
          }
        ],
        "contractsFound": 3,
        "openInterest": 2514201,
        "underlyingSpec": "The underlying is the political party whose members control at least 218 seats in the US House of Representatives on January 3rd of the year following a Congressional election. The list of US Representatives at the convening of each Congress is published January 4th on Congress.gov."
      }
    ],
    "page": 1,
    "perPage": 1,
    "type": "base-events"
  },
  "success": true
}

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.

`type`	Hit shape	Notes
`contracts` (default)	One hit per matching contract	Each hit carries its event’s and base event’s text flattened in.
`events`	One hit per event	Carries the event’s own fields, its total `openInterest`, `contractsFound`, and `contracts`: its first matching contracts in the `sortBy` order.
`base-events`	One hit per base event	Same, one level up. The index carries no display name — read it from Get Base Event.

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 events or base-events hit is the count of every matching contract under it, and contracts holds the first contractsPerHit of them (2 by default, at most 10). To list the rest, search again with type=contracts and the hit’s eventId or baseEventId. Contracts under the venue’s Conditional category are never returned. See Conditional contracts are not served.

Ordering

sortBy picks the order:

`sortBy`	Order
`none` (default)	A `q` match first, then symbol A to Z, at every level: hits, and the `contracts` on each hit. Pages stay stable from one request to the next.
`openInterest`	By open interest, as described below.

Any other value returns 400 INVALID_SORT_BY.

Ordering by open interest

With sortBy=openInterest, results are ordered by open interest, from the venue’s last daily prices file. Each type ranks by its own level:

`type`	Ranked by
`contracts`	The contract’s own `openInterest`
`events`	The event’s total `openInterest`, the sum over all of its active contracts, matching or not
`base-events`	The base event’s total `openInterest`, the sum over all of its active contracts

The contracts on a hit come in order of their own open interest, highest first. Ties are broken by symbol, so pages are stable. With q, relevance comes first and open interest breaks ties. The file is published once a day, after the close, so open interest is end of day, not live. A contract the file did not name has no openInterest field and comes last; 0 is a real value. A hit’s openInterest is absent when the file named none of its contracts.

Search carries no prices. To show a price for the contracts on screen, open one live price stream for their symbols: its first snapshot per contract has each outcome’s last, and contract.settlement when nothing has traded yet.

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:

GET /v1/predictions/search?q=BPM 0822        → matches BPM_0822_1750
GET /v1/predictions/search?q=unemployment june

Omit q entirely to browse the catalogue, in the sortBy order.

Parameters

Parameter	Type	Default	Description
`type`	string	`contracts`	`contracts`, `events`, or `base-events`. Echoed in `data.type`.
`q`	string	—	Full-text query. Omit to browse.
`state`	string	`ACTIVE`	Contract state. Use `*` to match every state, including `DELETED`.
`baseEventId`	string	—	Restrict to contracts under this base event.
`eventId`	string	—	Restrict to contracts under this event.
`category`	string	—	Restrict to contracts in this category or any category under it. Takes a `path` from List Categories.
`tradable`	boolean	—	Restrict to tradable (`true`) or non-tradable (`false`) contracts.
`sortBy`	string	`none`	`none` (a `q` match, then symbol) or `openInterest`. See Ordering.
`page`	integer	`1`	1-based page number. `0` or omitted means 1.
`perPage`	integer	`20`	Hits per page. `0` or omitted means 20; values above 100 are clamped to 100.
`contractsPerHit`	integer	`2`	With `type=events` or `base-events`, how many of each hit’s matching contracts to return in `contracts`, in the `sortBy` order. `0` or omitted means 2; values above 10 are clamped to 10. Ignored by `type=contracts`.

Filter by category

category takes a category’s whole path, such as Elections > United States House, from List Categories. It matches that category and everything under it, so Elections also finds every House and Senate race. A bare level name such as United States matches nothing, because level names repeat under different parents. URL-encode the path, since it contains spaces and >.

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

This response is for type=events&sortBy=openInterest, so each hit’s contracts come most open interest first.

{
  "success": true,
  "data": {
    "type": "events",
    "found": 3986,
    "page": 1,
    "perPage": 20,
    "hits": [
      {
        "eventId": "HORC_1126",
        "baseEventId": "HORC",
        "eventDisplayName": "US House of Representatives Control November 2026",
        "openInterest": 2514201,
        "contractsFound": 2,
        "contracts": [
          {
            "symbol": "HORC_1126_Republican",
            "eventId": "HORC_1126",
            "baseEventId": "HORC",
            "symbolSubTypes": ["YES", "NO"],
            "state": "ACTIVE",
            "tradable": true,
            "tickSize": "0.01",
            "openInterest": 1309471,
            "photo": null,
            "party": null,
            "frontRunner": null,
            "incumbent": null,
            "candidateStatus": null
          },
          {
            "symbol": "HORC_1126_Democratic",
            "eventId": "HORC_1126",
            "baseEventId": "HORC",
            "symbolSubTypes": ["YES", "NO"],
            "state": "ACTIVE",
            "tradable": true,
            "tickSize": "0.01",
            "openInterest": 1204730,
            "photo": null,
            "party": null,
            "frontRunner": null,
            "incumbent": null,
            "candidateStatus": null
          }
        ]
      }
    ]
  }
}

Every contract, whether a contracts hit or inside an event or base-event hit, carries photo: the candidate’s portrait on an election contract that has one, else null (as on the House-control outcomes above). It is the same object Get Event Contracts returns:

"photo": {
  "url": "https://d3db84syzhd30r.cloudfront.net/2026/AXXTX_110326_JT.webp",
  "credit": "Antonioaesparza",
  "license": "CC BY-SA 4.0",
  "licenseUrl": "https://creativecommons.org/licenses/by-sa/4.0",
  "sourceUrl": "https://commons.wikimedia.org/wiki/File:James_Talarico_Press_Conference.jpg"
}

Show credit and license with the image, or on a credits page it links to. Photos are on staging; on production photo is null until the rollout is announced in the changelog. Every contract also carries party, frontRunner, incumbent and candidateStatus: the venue’s metadata on an election contract, else null (as on the House-control outcomes above). They are read from the index, so like the rest of the hit they trail Get Event Contracts by seconds:

"party": "D",
"frontRunner": true,
"incumbent": false,
"candidateStatus": "C"

Examples

Find contracts by text

curl -X GET "https://api.aries.com/v1/predictions/search?q=unemployment%20june"

Group hits by event

curl -X GET "https://api.aries.com/v1/predictions/search?type=events&q=unemployment"

Rank events by open interest, with each one’s 3 most-held contracts

curl -X GET "https://api.aries.com/v1/predictions/search?type=events&sortBy=openInterest&contractsPerHit=3"

List the matching contracts under one event hit

curl -X GET "https://api.aries.com/v1/predictions/search?type=contracts&q=unemployment&eventId=UNR_0822"

Browse a single base event, tradable only

curl -X GET "https://api.aries.com/v1/predictions/search?baseEventId=UNR&tradable=true&perPage=50"

Search one category

curl -G "https://api.aries.com/v1/predictions/search" \
  --data-urlencode "category=Elections > United States House" \
  -d type=base-events

Include deleted contracts

curl -X GET "https://api.aries.com/v1/predictions/search?q=unemployment&state=*"

Errors

400 — an unknown type, a parameter that failed validation (such as INVALID_CONTRACTS_PER_HIT for a negative or non-integer contractsPerHit, or INVALID_SORT_BY for a sortBy other than none or openInterest), or a category containing a backtick
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 with its own fields, a count of matching contracts and the first contractsPerHit of them in the sortBy order. Echoed in the response.

Available options:

contracts,

events,

base-events

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, in the sortBy order.

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"

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.

Option 1
Option 2
Option 3

Show child attributes

Historical Data

Reference Data

Elections

Live Data

Orders

Search Prediction Market

Overview

Filters apply to contracts

Ordering

Ordering by open interest

Query syntax

Parameters

Filter by category

Search results trail the catalogue

Response

Examples

Find contracts by text

Group hits by event

Rank events by open interest, with each one’s 3 most-held contracts

List the matching contracts under one event hit

Browse a single base event, tradable only

Search one category

Include deleted contracts

Errors

Query Parameters

Response

​Overview

​Filters apply to contracts

​Ordering

​Ordering by open interest

​Query syntax

​Parameters

​Filter by category

​Search results trail the catalogue

​Response

​Examples

​Find contracts by text

​Group hits by event

​Rank events by open interest, with each one’s 3 most-held contracts

​List the matching contracts under one event hit

​Browse a single base event, tradable only

​Search one category

​Include deleted contracts

​Errors

Query Parameters

Response

Overview

Filters apply to contracts

Ordering

Ordering by open interest

Query syntax

Parameters

Filter by category

Search results trail the catalogue

Response

Examples

Find contracts by text

Group hits by event

Rank events by open interest, with each one’s 3 most-held contracts

List the matching contracts under one event hit

Browse a single base event, tradable only

Search one category

Include deleted contracts

Errors