Datasets

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, 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 datasetsCopy Anchor Link

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 datasetCopy Anchor Link

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

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

SAMPLE response (shortened):

{
  "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.

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

Who can see a datasetCopy Anchor Link

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.