> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polytape.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Tapes

> Your recorded watch sessions over REST — the cassette library, one tape's metadata, its parsed events, and the bulk export.

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.

<Note>
  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.
</Note>

<Warning>
  **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.
</Warning>

***

## `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) |

```json theme={null}
{ "tapes": [ … ], "count": 12 }
```

<Tip>
  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.
</Tip>

***

## `GET /tapes/{tape_id}`

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

```json theme={null}
{ "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.

```json theme={null}
{ "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](/errors).