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

# Downloads

> Get every file a run or a browser session downloaded.

Every file the browser downloads is kept for you: in an agent run, and in a browser you drive yourself with `oc.browser()`. An invoice PDF, a CSV export, a statement: list the run's downloads and fetch the bytes.

* **What is kept:** every file the browser downloads, up to 200 MB each.
* **How long:** 7 days from when it was downloaded. `expiresAt` says when.
* **What it costs:** nothing extra. Keeping, listing and fetching files is free.
* **The link:** each file comes with a `url` that works for one hour and needs no API key. Anyone who has the link can fetch the file until it expires, so treat it like a password: share it only with whoever should get the file. List again for a fresh one.

A file shows up as soon as its download finishes. A run waits for downloads still in progress before it ends, so a list taken right after the run ends has all of them.

## List a run's downloads

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"catppuccin-mocha"}}
import { mkdir } from 'node:fs/promises';
import { Outcrawl, saveDownload } from '@outcrawl/sdk';

const oc = new Outcrawl();
const downloads = await oc.agent.downloads('<id>');
await mkdir('./files', { recursive: true });
for (const download of downloads) {
  const path = await saveDownload(download, './files');
  console.log(download.name, download.bytes, download.sourceUrl, path);
}
```

```python Python theme={"theme":{"light":"github-light","dark":"catppuccin-mocha"}}
import asyncio
from pathlib import Path
from outcrawl import Outcrawl, save_download

async def main():
    async with Outcrawl() as oc:
        downloads = await oc.agent.downloads("<id>")
        Path("./files").mkdir(exist_ok=True)
        for download in downloads:
            path = await save_download(download, "./files")
            print(download["name"], download["bytes"], download["sourceUrl"], path)

asyncio.run(main())
```

```bash CLI theme={"theme":{"light":"github-light","dark":"catppuccin-mocha"}}
mkdir -p files
outcrawl agent downloads <id> --save ./files
```

```bash curl theme={"theme":{"light":"github-light","dark":"catppuccin-mocha"}}
curl https://api.outcrawl.ai/v1/agent/<id>/downloads \
  -H "Authorization: Bearer ock_YOUR_KEY_ID.YOUR_SECRET"
```

On a job you already hold, `job.downloads()` does the same in both SDKs. Without `--save`, the CLI prints the list and saves nothing.

Over MCP, an assistant calls `outcrawl_agent_downloads` for a run and `outcrawl_session_downloads` for a browser session.

## Save a file

`saveDownload(download, dir)` in TypeScript and `save_download(download, directory)` in Python write one file into a folder that already exists, and answer the path they wrote. The CLI's `--save` does the same for every file in the list.

* The file is named after `name`. Characters a file name cannot hold, control characters and text direction marks become `_`. Long names are cut to 230 bytes. A name Windows keeps for a device, such as `CON` or `NUL.txt`, gets `_` in front.
* An existing file is never overwritten. If the name is taken, the first 8 characters of the download's `id` go before the extension, for example `invoice-8f0c1a2b.pdf`.
* The bytes are written to disk as they arrive, so a 200 MB file is never held in memory.
* If fewer bytes arrive than `bytes` says, the partial file is deleted and the call fails. List again and retry.

## Downloads in a browser session

A browser you drive with `oc.browser()` keeps its downloads too. Call `browser.downloads()` while it is open, or `oc.sessions.downloads(sessionId)` at any time in the next 7 days. See [sessions](https://outcrawl.ai/docs/browsers/sessions.md#downloads) for an example.

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"catppuccin-mocha"}}
import { Outcrawl } from '@outcrawl/sdk';

const oc = new Outcrawl();
const downloads = await oc.sessions.downloads('<session id>');
for (const download of downloads) console.log(download.name, download.url);
```

```python Python theme={"theme":{"light":"github-light","dark":"catppuccin-mocha"}}
import asyncio
from outcrawl import Outcrawl

async def main():
    async with Outcrawl() as oc:
        downloads = await oc.sessions.downloads("<session id>")
        for download in downloads:
            print(download["name"], download["url"])

asyncio.run(main())
```

```bash CLI theme={"theme":{"light":"github-light","dark":"catppuccin-mocha"}}
outcrawl sessions downloads <session id> --save ./files
```

```bash curl theme={"theme":{"light":"github-light","dark":"catppuccin-mocha"}}
curl https://api.outcrawl.ai/v1/sessions/<session id>/downloads \
  -H "Authorization: Bearer ock_YOUR_KEY_ID.YOUR_SECRET"
```

A session from `oc.sessions.get(id)` in TypeScript also carries `session.downloads()`.

### Playwright's own download event

With `oc.browser()`, Playwright's own `download` event works as usual. `download.saveAs()`, `download.path()` and `download.createReadStream()` give you the file: each one waits until the file is kept, for up to 2 minutes after it finishes downloading, and then fetches it.

```typescript theme={"theme":{"light":"github-light","dark":"catppuccin-mocha"}}
const pw = page.raw as unknown as Page; // import type { Page } from 'playwright'
const downloading = pw.waitForEvent('download');
await page.click('#export-csv');
await (await downloading).saveAs('./export.csv');
```

`page.raw.on('download', ...)` works the same way, on popups too. If a file was not kept, for example because it is over 200 MB, `download.failure()` says why and `saveAs()` fails with the same reason.

> [!NOTE]
>
> Connecting Playwright or Puppeteer to the browser without the TypeScript SDK, from Python or any other language? The browser runs on Outcrawl's machines, so Playwright's `saveAs()` and `path()` look for the file on your disk and find nothing. List the session's downloads instead, and match the file by its `sourceUrl` and `name`.

```python Python theme={"theme":{"light":"github-light","dark":"catppuccin-mocha"}}
import asyncio
from outcrawl import save_download

async def save_kept(oc, session_id, download, directory="."):
    """download is Playwright's Download. session_id is the session's id, as oc.sessions.list() shows it."""
    await download.failure()  # returns once the browser has finished the download
    for _ in range(60):
        kept = await oc.sessions.downloads(session_id, limit=1000)
        found = [d for d in kept if d["sourceUrl"] == download.url and d["name"] == download.suggested_filename]
        if found:
            newest = max(found, key=lambda d: d["createdAt"])
            return await save_download(newest, directory)
        await asyncio.sleep(2)
    raise RuntimeError(f"{download.suggested_filename} is not in the session's downloads")
```

If the same URL was downloaded more than once, the newest `createdAt` is the latest copy.

## What a list holds

`GET /v1/agent/{id}/downloads` and `GET /v1/sessions/{id}/downloads` answer the same shape:

```json theme={"theme":{"light":"github-light","dark":"catppuccin-mocha"}}
{
  "data": [
    {
      "id": "8f0c1a2b-5d1e-4c33-9a70-2e6b1d0f4c11",
      "name": "invoice-2026-10.pdf",
      "contentType": "application/pdf",
      "bytes": 48213,
      "sourceUrl": "https://vendor.example/invoices/123.pdf",
      "createdAt": "2026-10-19T10:00:00.000Z",
      "expiresAt": "2026-10-26T10:00:00.000Z",
      "url": "https://api.outcrawl.ai/dl/<token>"
    }
  ],
  "usage": {}
}
```

| Field | Meaning |
| - | - |
| `id` | The download's id. It stays the same every time you list. |
| `name` | The file name the site gave it. |
| `contentType` | The file's type, such as `application/pdf`. |
| `bytes` | Its size. |
| `sourceUrl` | The URL it was downloaded from. |
| `createdAt` | When the download finished. |
| `expiresAt` | When it is deleted, 7 days after `createdAt`. |
| `url` | A link to the bytes. It works for one hour and needs no API key. |

`data` is empty when nothing was downloaded. A run or session that does not exist, or belongs to another account, answers `404 not_found`.

The list comes a page at a time. When there is another page, the answer carries a `cursor`: pass it back as `?cursor=` to read the next one. `?limit=` sets the page size, from 1 to 1000. In the SDKs the list is an array with a `cursor` beside it, so `oc.agent.downloads(id, { cursor: downloads.cursor })` in TypeScript and `oc.agent.downloads(run_id, cursor=downloads.cursor)` in Python read the next page.

## Fetch the bytes

```bash theme={"theme":{"light":"github-light","dark":"catppuccin-mocha"}}
curl -OJ "https://api.outcrawl.ai/dl/<token>"
```

Send the link without your API key. It answers the bytes as `application/octet-stream`, with `Content-Length` and a `Content-Disposition` that carries the file name, so `curl -OJ` saves it under that name. The file's real type is `contentType` in the list. The link is a bearer link: it works for whoever holds it, for one hour, even if your API key is revoked or the request comes from outside your key's allowed IPs. After an hour, or once the file has been deleted, it answers `404`. List again for a fresh link while the file is still kept.

> [!NOTE]
>
> Anyone holding a link can fetch the file for that hour. Treat it like the file itself.

## Related

> [card] [Files](https://outcrawl.ai/docs/agents/files.md)
>
> Hand a file to a run so it can upload it.

> [card] [Monitoring](https://outcrawl.ai/docs/agents/monitoring.md)
>
> Status, events and results of a run.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.