Result Files & Downloads
When a runner (a single execution of a Collection) finishes, the platform writes a structured set of result files to owner-scoped storage and exposes them as download links on the runner record.
What gets produced
Every runner produces a result set — the files differ slightly between Amazon product scrapes and Amazon category scrapes.
Amazon product scrapes
| File | Description |
|---|---|
{CollectionName}_{runner_id}_Results_Page_1.json | Page 1 of scraped item data |
{CollectionName}_{runner_id}_Results_Page_2.json | Page 2 (if the collection has more items than fit on one page) |
{CollectionName}_{runner_id}_Results_All_Pages.zip | ZIP containing every page JSON in one archive |
Items are written page-by-page as scraping completes, so the page files appear incrementally. The ZIP is generated last, once all pages are present.
Amazon category scrapes
| File | Description |
|---|---|
category_asins.json | All discovered ASINs with title, price and metadata |
| A CSV export (auto-generated) | The same ASIN list in spreadsheet-friendly format |
Category results are inlined too
When you poll POST /schedules/amazon/category/result/, the asins array in the response body is
read directly from category_asins.json — you can consume the data without a separate download step
if you prefer.
is_download_generated
The runner record carries a boolean field is_download_generated. This is the authoritative signal
that the result set is complete and all files are available for download.
false— the runner is still in progress, or files are being written. Do not attempt to download yet.true— all page files and the ZIP have been written. Download links indownload_linksare live.
Poll POST /schedules/collections/results/download/ and wait for is_download_generated: true
before fetching files.
Do not download before is_download_generated is true
Attempting to stream a result file before is_download_generated flips to true may return a
partial file or a 404. Always check this flag first.
Polling for results
Poll run history and download links
https://multicartapi.com/api/v1/schedules/collections/results/download/Request body
| Parameter | Type | Required | Description |
|---|---|---|---|
collection_id | integer | Required | The Collection ID to fetch runner history for. |
skip | integer | Optional | Pagination offset — number of runner rows to skip. |
limit | integer | Optional | Number of runner rows to return per page. |
{
"code": 200,
"status": 1,
"data": [
{
"id": 88,
"collection": 101,
"is_download_generated": true,
"total_exacted_result": 250,
"total_results": 250,
"download_links": {
"pages": [
"https://multicartapi.com/api/v1/results/101/88/AU%20Laptops_88_Results_Page_1.json",
"https://multicartapi.com/api/v1/results/101/88/AU%20Laptops_88_Results_Page_2.json"
],
"all_pages": "https://multicartapi.com/api/v1/results/101/88/AU%20Laptops_88_Results_All_Pages.zip"
},
"created_at": "2026-06-20T08:00:00Z",
"updated_at": "2026-06-20T08:04:31Z"
}
]
}The download_links.pages array lists every page JSON in order. download_links.all_pages is the
ZIP. Both are fully-formed URLs that include your collection and runner IDs in the path.
Streaming a result file
Files are served through an owner-scoped streaming endpoint. The server validates that the
collection_id in the URL belongs to the authenticated user before streaming.
Stream a result file
https://multicartapi.com/api/v1/results/{collection_id}/{runner_id}/{file_name}URL parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
collection_id | integer | Required | Collection ID. |
runner_id | integer | Required | Runner ID. |
file_name | string | Required | Exact file name, e.g. AU Laptops_88_Results_Page_1.json or AU Laptops_88_Results_All_Pages.zip (the space in the collection name is URL-encoded as %20 in the request path). |
The response is Content-Type: application/octet-stream with Content-Disposition: attachment —
there is no JSON envelope. Pipe it directly to a file.
curl -O \
-H "x-api-key: YOUR_API_KEY" \
"https://multicartapi.com/api/v1/results/101/88/AU%20Laptops_88_Results_All_Pages.zip"Use the URLs from the poll response
Always use the exact download_links URLs returned by POST /schedules/collections/results/download/
rather than constructing them manually. File names include the collection name and runner ID, which
can contain spaces encoded as %20.
File storage path
On the server, result files are stored at:
results/{user_id}/{collection_id}/{runner_id}/{file_name}
The URL path omits user_id — ownership is enforced by the authenticated user's session, not the
URL. A request for a collection that belongs to a different user will be rejected.
Downloads page in the dashboard
The Downloads tab on any Collection shows the full run history with pill-style status badges and direct download buttons for each page file and the ZIP.
