# Datasets

> Large runs are saved as CSV, Excel and JSON files for 30 days. List them and get private download links.

When a run returns **50 or more results**, its results are also saved as a dataset: one CSV file, one Excel file and one JSON file. Smaller runs that still produce a lot of data (512 KB of JSON or more) are saved too. You find every dataset in the dashboard under **Datasets**, and through the API.

Datasets are kept for **30 days**. After that the files are deleted for good. The run itself and its results stay in [Runs](/docs/runs), so you can still fetch them with `GET /api/v1/runs/{id}/results`.

Saving a dataset never costs extra credits and never slows a run down by more than a few seconds. If saving fails, the run is not affected.

## List your datasets [#list-your-datasets]

```bash
curl "https://actor-factory-web.vercel.app/api/v1/datasets" -H "x-api-key: $AF_API_KEY"
```

Add `?runId=<run id>` to get only the dataset of one run. The answer lists each dataset with its run, tool, number of results, size and the time it expires.

## Download a dataset [#download-a-dataset]

Ask for one dataset to get a download link per format:

```bash
curl "https://actor-factory-web.vercel.app/api/v1/datasets/$DATASET_ID" -H "x-api-key: $AF_API_KEY"
```

SAMPLE response (shortened):

```json
{
  "dataset": {
    "id": "6f1c2a9e-0000-4000-8000-000000000000",
    "runId": "1a2b3c4d-0000-4000-8000-000000000000",
    "toolId": "maps-leads",
    "status": "ready",
    "items": 120,
    "formats": ["csv", "xlsx", "json"],
    "expiresAt": "2026-11-20T10:00:00.000Z"
  },
  "downloads": {
    "csv": { "url": "https://…", "filename": "maps-leads-1a2b3c4d.csv", "expiresAt": "…" }
  }
}
```

Each link is private and works for **15 minutes**, without an API key, so you can hand it to a script or a browser. Ask again for a fresh link.

```bash
curl -L "$CSV_URL" -o leads.csv
```

## Who can see a dataset [#who-can-see-a-dataset]

Only your organization. A dataset ID of another organization answers `404 NOT_FOUND`, exactly like an ID that does not exist. The files sit in a private store; the only way to read them is a link you got from the API or the dashboard.