---
updatedAt: 2026-09-14T15:25:43.000Z
agentTools:
projectIndex: https://readme.priceapi.com/llms.txt
---
# /jobs/:job_id/download
Step 3: Download a finished job's results.
### Follow redirects
For performance reasons, we sometimes pre-render your results. If we do so, we will respond with a redirect. Please make sure, your client follows redirects when you request results.
## Result formats
We currently can give you the job results in four different formats:
* JSON (recommended for integration)
* XML
* CSV (for most topics)
* XSLX (for most topics)
```json JSON
{
"job_id": "1234567890abcdef12345678",
"status": "finished",
"free_credits": 2,
"paid_credits": 0,
"results": [
{
"query": {
"source": "test",
"country": "us",
"topic": "search_results",
"key": "gtin",
"value": "00885909666966",
"max_pages": 1,
"max_age": 1200
},
"success": true,
"metadata": {
"from_cache": false,
"page_count_delivered": 2,
"page_count_from_cache": 0,
"page_count_live": 2,
"request_count": 3,
"updated_at": "2017-06-08T12:34:37Z",
"tag": "2017_06_01-10_03_51"
},
"content": {
"search_results": [
{
"id": "product_0",
"updated_at": "2017-06-08 12:34:37 UTC",
"url": "https://test.priceapi.com/products/product_0",
"name": "00885909666966 Result 0"
},
{
"id": "product_1",
"updated_at": "2017-06-08 12:34:37 UTC",
"url": "https://test.priceapi.com/products/product_1",
"name": "00885909666966 Result 1"
},
// ... more search results
]
}
},
// ... next search
]
}
```
```xml XML
1234567890abcdef12345678finished20testussearch_resultsgtin0088590966696611200truefalse20232017-06-08T12:34:37Zproduct_02017-06-08T12:34:37Zhttps://test.priceapi.com/products/product_000885909666966 Result 0product_12017-06-08T12:34:37Zhttps://test.priceapi.com/products/product_100885909666966 Result 1
```
### 72 hour retention period
Job results are only available for 72 hours after the job was requested. After that we permanently delete the results. So please make sure to download the results shortly after the job finishes.
## List of error codes
| Error code | Meaning |
| :----------------- | :----------------------------------------------------------------------------- |
| `unauthorized` | No `token` given or `token` is not valid. |
| `job not found` | No job could found for given `job_id`. |
| `job forbidden` | User with given `token` is not allowed access to the given job. |
| `job not finished` | Job processing is still in progress. Wait until its `status` it is `finished`. |
Further error codes may be added.
# Product-level errors
Even when a job is accepted, there may be errors while collecting data on individual products. This is indicated with the `success` attribute being `false` and with a given `reason` attribute.
**When an error occurs, we don't deduct any credits.**
*The only exception is for reason*`not found`* (see below) as this is a valid response and it takes us the same amount of effort to find this out.*
## List of reasons
| Reason codes | Meaning |
| :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `not found` | We have successfully searched for the given product, but it is not currently present on the `source`. |
| `invalid value` | We have checked the `value` and found that it is invalid. We did not try to request this. For example, if you search with `key=gtin` we will check the provided GTIN's checksum. |
| `timeout` | We could not collect the data in the timespan allowed by you. See job parameter `timeout`. |
| `error` | General error in our processing. |
| `daily quota exceeded` | Your daily quota was used up before we got to this value. We did not deduct any credits for it. |
Additional reasons specific to the product matching topic can be found in this [article](https://readme.priceapi.com/reference/product-matching).
# OpenAPI definition
```json
{
"openapi": "3.1.0",
"info": {
"title": "price-api",
"version": "2"
},
"servers": [
{
"url": "https://priceapi.metoda.com/v2"
}
],
"components": {
"securitySchemes": {
"sec0": {
"name": "token",
"in": "query",
"x-default": "YOUR_API_KEY",
"type": "apiKey"
}
}
},
"security": [
{
"sec0": []
}
],
"paths": {
"/jobs/{job_id}/download": {
"get": {
"summary": "/jobs/:job_id/download",
"description": "Step 3: Download a finished job's results.",
"operationId": "v2-get-job-results",
"parameters": [
{
"name": "job_id",
"in": "path",
"description": "The id of a recently created job. Found in the JSON response of the create request.",
"schema": {
"type": "string",
"default": "See step 1"
},
"required": true
},
{
"name": "token",
"in": "query",
"description": "Your API key",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "layout",
"in": "query",
"description": "Only when format is CSV or Excel. Available layouts depend on the topic, e.g. be `one_product_per_row` or `one_offer_per_row`.",
"schema": {
"type": "string"
}
},
{
"name": "job_id",
"in": "query",
"description": "The ID of your job.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200",
"content": {
"application/json": {
"examples": {
"Result": {
"value": "{\n \"job_id\": \"1234567890abcdef12345678\",\n \"status\": \"finished\",\n // used test credits for this request\n \"free_credits\": 0,\n // used paid credits for this requests\n \"paid_credits\": 4,\n // array including multiple entries\n \"results\": [\n // Multiple results here (see below)\n ]\n}"
}
},
"schema": {
"type": "object",
"properties": {
"job_id": {
"type": "string",
"example": "1234567890abcdef12345678"
},
"status": {
"type": "string",
"example": "finished"
},
"free_credits": {
"type": "integer",
"example": 0,
"default": 0
},
"paid_credits": {
"type": "integer",
"example": 4,
"default": 0
},
"results": {
"type": "array"
}
}
}
}
}
},
"302": {
"description": "302",
"content": {
"text/plain": {
"examples": {
"Result": {
"value": "HTTP/1.1 302 Found\nLocation: https://api.priceapi.com/results/1234567890abcdef12345678.json?code=ABC123"
}
}
}
}
},
"410": {
"description": "Gone",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"job_id": {
"type": "string",
"description": "The id of the job requested",
"default": "1234567890abcdef12345678"
},
"expires_at": {
"type": "string",
"description": "When the job expired.",
"format": "date-time",
"default": "2017-06-11T12:34:37Z"
},
"Success": {
"type": "boolean",
"default": "false"
},
"reason": {
"type": "string",
"default": "job expired"
},
"comment": {
"type": "string",
"default": "The job with id '1234567890abcdef12345678' expired at 2017-06-11 12:34:37 UTC and can not be downloaded anymore."
}
},
"required": [
"job_id",
"expires_at",
"Success",
"reason",
"comment"
]
}
}
}
},
"503": {
"description": "503",
"content": {
"application/json": {
"examples": {
"Result": {
"value": "{\n \"success\": false,\n \"reason\": \"job not finished\",\n \"comment\": \"The job with id '1234567890abcdef12345678' is not finished, yet! Status: finishing\",\n \"status\": \"finishing\"\n}"
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"example": false,
"default": true
},
"reason": {
"type": "string",
"example": "job not finished"
},
"comment": {
"type": "string",
"example": "The job with id '1234567890abcdef12345678' is not finished, yet! Status: finishing"
},
"status": {
"type": "string",
"example": "finishing"
}
}
}
}
}
}
},
"deprecated": false,
"x-readme": {
"code-samples": [
{
"language": "curl",
"code": "# Assuming you stored your API key in environment variable PRICEAPI_TOKEN\n# JSON is the default\ncurl -L https://priceapi.metoda.com/v2/jobs/1234567890abcdef12345678/download?token=$PRICEAPI_TOKEN\n\n# Explicitly select JSON\ncurl -L https://priceapi.metoda.com/v2/jobs/1234567890abcdef12345678/download.json?token=$PRICEAPI_TOKEN\n# Select XML\ncurl -L https://priceapi.metoda.com/v2/jobs/1234567890abcdef12345678/download.xml?token=$PRICEAPI_TOKEN\n# Select CSV\ncurl -L https://priceapi.metoda.com/v2/jobs/1234567890abcdef12345678/download.csv?token=$PRICEAPI_TOKEN&layout=one_offer_per_row\n# Select Excel\ncurl -L https://priceapi.metoda.com/v2/jobs/1234567890abcdef12345678/download.xlsx?token=$PRICEAPI_TOKEN&layout=one_offer_per_row"
},
{
"language": "ruby",
"code": "require \"net/http\"\nrequire \"json\"\n\nAPI = \"https://priceapi.metoda.com/v2\"\nENDPOINT = \"/jobs/\" + ENV[\"PRICEAPI_JOB_ID\"] + \"/download\"\nTOKEN = ENV[\"PRICEAPI_TOKEN\"]\n\nresponse = Net::HTTP.get_response(URI(API + ENDPOINT + \"?token=#{TOKEN}\"))\nresult = JSON.parse(response.body)\nputs JSON.pretty_generate(result)\n"
},
{
"language": "python",
"code": "import os\nimport urllib.request\nimport json\n\nAPI = \"https://priceapi.metoda.com/v2\"\nENDPOINT = \"/jobs/\" + os.environ[\"PRICEAPI_JOB_ID\"] + \"/download\"\nTOKEN = os.environ[\"PRICEAPI_TOKEN\"]\n\nurl = API + ENDPOINT + \"?token=\" + TOKEN\nresponse = urllib.request.urlopen(url)\nresult = json.loads(response.read())\nprint(json.dumps(result, indent=4))\n"
}
],
"samples-languages": [
"curl",
"ruby",
"python"
]
}
}
}
},
"x-readme": {
"headers": [],
"explorer-enabled": true,
"proxy-enabled": true
},
"x-readme-fauxas": true
}
```