---
title: "Get a trader's position timeline for one market"
method: GET
path: "/api/v1/trader/{address}/position-timeline"
tags: ["Traders"]
---

# Get a trader's position timeline for one market

`GET /api/v1/trader/{address}/position-timeline`

Returns every Polymarket fill for one trader in one market, newest first, with server-computed running_amount and running_avg_price. Only HOT and WARM tier traders are tracked; other traders return 404. running_avg_price is a buy-weighted entry basis (sells do not change the running average) matching Polymarket /positions avgPrice semantics. Cursor-paginated. An id-keyed alias exists at GET /api/v1/traders/{id}/position-timeline.

## Path parameters

- `address` string, required

## Query parameters

- `condition_id` string, required
- `limit` integer
- `cursor` string

## Headers

- `If-None-Match` string

## Response `200`

Position timeline page

- object
  - `object` 'list', required
  - `data` PositionTimelineEvent[], required
    - `id` string, required — Prefixed ID (pe_...).
    - `event_timestamp` string, date-time, required — ISO 8601 timestamp of the on-chain fill.
    - `action` 'buy' | 'sell', required — From the taker's perspective.
    - `outcome_side` 'yes' | 'no', required
    - `token_id` string, nullable — The Polymarket CLOB token id (ERC1155 asset id, decimal string) for this outcome; null when unavailable (e.g. Kalshi markets, unsynced markets).
    - `amount_delta` number, required — Signed share delta (+ on buy, − on sell).
    - `price` number, required — Fill price in USDC per share, in [0,1].
    - `usdc_notional` number, required — Positive USDC notional of the fill.
    - `tx_hash` string, required — Polygon transaction hash of the fill.
    - `running_amount` number, required — Cumulative signed share balance after this fill.
    - `running_avg_price` number, required — Buy-weighted entry basis (matches Polymarket /positions avgPrice semantics). Sells do not change this value. 0 when no buys have occurred yet.
  - `has_more` boolean, required
  - `next_cursor` string, nullable
  - `meta` ResponseMeta, required
    - `request_id` string, required — Unique request ID (req_ prefix).
    - `cached` boolean, required
    - `cache_age_s` integer, nullable — Cache age in seconds, null if not cached.

## Other responses

- `304` — Not Modified. Returned when If-None-Match matches the current payload.
- `400` — Invalid request parameter
- `401` — Missing or invalid API key
- `402` — Active Insider subscription required
- `403` — Account access denied
- `404` — Resource not found
- `408` — Request exceeded the server's 30-second transport timeout. The timeout response has an empty body because it is generated before handler-level JSON error shaping.
- `423` — Account is locked
- `429` — Rate limit exceeded (100 req/min; batch endpoints also reserve 100 batch item units/min before execution)
- `500` — Unexpected server error
- `503` — Redis-backed authenticated rate limiter unavailable; retry after the per-process outage cooldown

## Changes

- **2026-07-01** `1777a41bfb53` — 1 info
  - added the optional property `data/items/token_id` to the response with the `200` status
- **2026-06-01** `422bd4dc1611` — 81 warning, 3 info
  - added the new `account_locked` enum value to the `error/code` response property for the response status `400`
  - added the new `account_locked` enum value to the `error/code` response property for the response status `401`
  - added the new `account_locked` enum value to the `error/code` response property for the response status `402`
  - added the new `account_locked` enum value to the `error/code` response property for the response status `403`
  - …80 more
- **2026-05-07** `2907497f4ca3` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/0xinsider/apis/0xinsider-api/changes/api/v1/trader/:address/position-timeline/get.md)

---

[API](https://skmtc.dev/0xinsider/apis/0xinsider-api.md) · [All operations](https://skmtc.dev/0xinsider/apis/0xinsider-api/llms.txt) · [OpenAPI document](https://skmtc.dev/0xinsider/apis/0xinsider-api/revisions/137fa0fd3297?raw)