Skip to main content
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

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 for an example.
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.
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.
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
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:
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

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.
Anyone holding a link can fetch the file for that hour. Treat it like the file itself.

Files

Hand a file to a run so it can upload it.

Monitoring

Status, events and results of a run.