Search endpoint

Find prediction markets related to a topic or question.

Quick start

Call Search

Search can run without an API key. Add an API key for higher usage.

EndpointPOST /v1/search

Base URLhttps://api.polybridge.ai

AuthAnonymous access or API key. Use an API key for higher usage.

OutputMarkets grouped by search dimension

ScoreRelevance ranking

Anonymous Search (no key)

curl -sS -X POST "https://api.polybridge.ai/v1/search" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Fed rate cut before September 2026",
    "dimensions": ["direct", "correlated"],
    "top_k_per_dimension": 3,
    "filters": { "status": "active" }
  }'

API-key Search (higher usage)

curl -sS -X POST "https://api.polybridge.ai/v1/search" \
  -H "Authorization: Bearer $POLYBRIDGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Fed rate cut before September 2026",
    "dimensions": ["direct", "correlated"],
    "top_k_per_dimension": 3,
    "filters": {"status": "active"}
  }'

A successful response includes request_id, grouped results, total_markets, and latency_ms.

Request and response shape

Search accepts a query plus optional dimensions, result count, and status filter.

Request fields

queryrequired
Topic, question, or short search phrase.
dimensionsoptional
One or more of "direct", "upstream", "downstream", or "correlated".
top_k_per_dimensionoptional
Maximum results to return for each dimension. Anonymous requests support up to 50.
filters.statusoptional
Market status filter. Use "active" for forward-looking work.

Response fields

request_id
ID for debugging and support.
query
The query string echoed back by the API.
results
Object keyed by dimension. Each dimension contains matching markets.
results[].id
PolyBridge market ID.
results[].platform
Source platform.
results[].question
Market question.
results[].outcomes
Outcome labels.
results[].status
active, closed, or resolved.
results[].platform_url
Source-platform URL when available.
results[].score
Relevance score. This is not a probability.
results[].dimension
Dimension that returned the result.
total_markets
Total markets returned across all dimensions.
latency_ms
Request latency in milliseconds.

Representative response

Values are illustrative. score is a ranking score, not a probability.

JSON response

{
  "request_id": "req_...",
  "query": "Fed rate cut before September 2026",
  "results": {
    "direct": [
      {
        "platform": "polymarket",
        "question": "Will no Fed rate cuts happen in 2026?",
        "status": "active",
        "score": 1.44
      }
    ],
    "correlated": []
  },
  "total_markets": 6,
  "latency_ms": 7549
}

Dimensions

By default, Search runs across all supported dimensions. Use dimensions only when you want to narrow the search.

direct
Markets that directly match the query.
upstream
Markets that describe causes or precursors.
downstream
Markets that describe consequences or follow-on events.
correlated
Markets related by broader thematic or market context.

Status filter values

active
Open markets that can still move.
closed
Markets that are no longer open but may not be resolved.
resolved
Markets with a final outcome.

Search limits

Use an API key for higher limits and higher result caps. See Rate Limits for exact limits and retry header behavior. See the Production guide for timeouts, retries, errors, and request IDs.

View rate limits

Endpoint behavior

Anonymous mode for Search works when no Authorization header is sent.
Invalid bearer credentials return 401 and do not fall back to Anonymous Search. Remove the Authorization header to use anonymous mode where supported.
Search scores rank relevance. They are not probabilities.
Use Forecast when you need a generated probability and evidence.