Tapes - PolyTape

Base: https://api.polytape.io/api/agent/v1 Tapes are yours — recorded watch sessions from the PolyTape web app, scoped to your account and private to it. This is the read layer for them.

Tapes are a different substrate from the archive. The archive is every Polymarket trader’s on-chain history; a tape is a session you recorded, replayed as the same StreamEvent vocabulary the live plane emits.

Recording a live market is a Pro/Max capability — watching and replaying are not, and never have been. Every plan can watch a live stream and scrub it back; Pro and Max add laying the session down as a tape you keep.The practical consequence for an agent: a Basic account can legitimately have an empty library, and these endpoints will honestly return count: 0. That is not an error and not a permissions failure — there is simply nothing on the shelf yet. Don’t retry it, and don’t report it as a fault.And don’t go looking for a way to start a recording from here on any plan. Recording is a web-app action; this API is read-only by construction, so there is no endpoint to find.

`GET /tapes`

Your cassette library with metadata: recorded market sessions with observed PnL (PNL · AS TAPED), outcome, duration, and tick/fill counts.

Query	Type	Notes
`wallet`	string	narrows to one trader’s folder
`limit`	int	caps the newest N (must be ≥ 1)

{ "tapes": [ … ], "count": 12 }

A large library is a token bomb — pass limit. The MCP list_tapes tool takes only wallet, so reach for REST when you need to cap.

`GET /tapes/{tape_id}`

One cassette: metadata plus summary counts. Cheap — prefer it over raw events.

{ "tape": { … } }

`GET /tapes/{tape_id}/events`

Parsed StreamEvent pages.

Query	Type	Notes
`cursor`	string	pass back `next_cursor`
`types`	string	comma list, e.g. `types=fill`
`limit`	int	events per page — pass a small one

A heavy read: it passes the admission lane, so overflow is 429 busy rather than a queue. Oversized tapes are pointed at /download instead of paged. To chart a market from a tape: book-tick and last-trade events form the price line (0–1), and the trader’s fills overlay as BUY-up / SELL-down markers at (ts, price), sized by usd.

`GET /tapes/{tape_id}/download`

A presigned .jsonl.gz URL, valid 1 hour — the bulk export path.

{ "url": "https://…", "expires_in": 3600 }

Once signed, fetching the object costs nothing against your API budget. This is the right way to pull a whole tape.

Errors

HTTP	error	meaning
404	`tape_not_found`	no such tape in your library — foreign and unknown ids are the same 404, with no existence leak
400	`bad_limit` / `bad_cursor` / `unknown_event_type`	malformed request
429	`busy`	admission lane full on a heavy read — retry in ~1s

Full table: Errors.

​GET /tapes

​GET /tapes/{tape_id}

​GET /tapes/{tape_id}/events

​GET /tapes/{tape_id}/download

​Errors

`GET /tapes`

`GET /tapes/{tape_id}`

`GET /tapes/{tape_id}/events`

`GET /tapes/{tape_id}/download`

Errors