---
title: "Search Kalshi series, or recent trades by series or trader"
method: GET
path: "/api/v1/search"
tags: ["Live (API key)"]
---

# Search Kalshi series, or recent trades by series or trader

`GET /api/v1/search`

## Request

- Base URL: `https://kalshispy.com`
- URL: `https://kalshispy.com/api/v1/search`
- Auth: HTTP bearer

Three modes. mode=title (default): free text → matching Kalshi series (ticker, title, category, volume) — use it to find the series_ticker for the other tools. mode=series: recent trades by named traders on that series ticker, with the settled P&L estimate or the current mark-to-market (at the bid/ask midpoint, or the last trade on a wide or empty book); a trade between two named traders is listed once for each, on opposite sides. mode=trader: a named trader's recent trades by nickname. `min_amount` filters by contracts per trade (0, 100, 500, 1000 or 5000). Requires a KalshiSpy API key.

## Query parameters

- `q` string, required
- `mode` 'title' | 'series' | 'trader'
- `min_amount` 0 | 100 | 500 | 1000 | 5000

## Response `200`

OK

- object
  - `ok` true, required
  - `data` TradeSearch, required
    - `mode` 'title' | 'series' | 'trader'
    - `series` object[]: mode=title only
      - `series_ticker` string
      - `title` string
      - `category` string
      - `volume` string
      - `market_count` integer
      - `kalshi_url` string, uri
    - `trades` object[]: mode=series / mode=trader only
      - `id` string: Unique within the response and the same in mode=series and mode=trader. A trade between two named traders gives two rows; the second trader's row id ends in `:maker`.
      - `nickname` string
      - `side` 'YES' | 'NO'
      - `ticker` string
      - `question` string
      - `category` string
      - `category_key` 'politics' | 'elections' | 'sports' | 'entertainment' | 'economics' | 'financials' | 'crypto' | 'weather' | 'world' | 'scitech' | 'companies' | 'health' | 'social' | 'transportation' | 'mentions' | 'exotics' | 'other'
      - `price_cents` integer
      - `contracts` integer
      - `notional_usd` number
      - `placed_ago` string
      - `market_closed` boolean
      - `pnl_est_usd` number, nullable
      - `pnl_cur_usd` number, nullable
      - `trader_lifetime_pnl_usd` number, nullable
  - `meta` Meta, required
    - `generated_at` string, date-time
    - `definition` string
    - `verification` string
    - `docs` string, uri
    - `attribution` string
  - `hints` Hints, required
    - `tip` string
    - `next_steps` object[]
      - `label` string
      - `url` string, uri
      - `auth` 'api_key'
    - `similar` SettledWin[]
      - `ticker` string
      - `title` string
      - `outcome` string: Kalshi's short outcome label; empty for plain Yes/No markets.
      - `category` string
      - `category_key` 'politics' | 'elections' | 'sports' | 'entertainment' | 'economics' | 'financials' | 'crypto' | 'weather' | 'world' | 'scitech' | 'companies' | 'health' | 'social' | 'transportation' | 'mentions' | 'exotics' | 'other'
      - `series_ticker` string
      - `event_ticker` string
      - `result` 'yes' | 'no'
      - `settled_at` string, date-time
      - `whale_count` integer
      - `dissent_count` integer
      - `consensus_side` 'YES' | 'NO'
      - `consensus_pct` number
      - `net_profit_usd` number
      - `winners_profit_usd` number
      - `whales` SettledWhale[]
        - `nickname` string
        - `side` 'YES' | 'NO'
        - `profit_usd` number
      - `url` string, uri
      - `kalshi_url` string, uri

## Other responses

- `400`: Invalid parameter (`error.param` names it) or invalid cursor.
- `401`: Missing, malformed, unknown or revoked API key.
- `403`: The plan on this account has no API access (`error.upgrade_url`).
- `429`: Daily quota reached; `Retry-After` and `error.resets_at` say when it resets.
- `503`: Temporarily unavailable; retry shortly. The quota unit is given back, up to a daily refund budget.

---

[API](https://skmtc.dev/kalshispy/apis/kalshispy-api.md) · [All operations](https://skmtc.dev/kalshispy/apis/kalshispy-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kalshispy/apis/kalshispy-api/revisions/5f483277dadc?raw)