---
updatedAt: 2026-06-08T08:53:12.000Z
agentTools:
  projectIndex: https://readme.priceapi.com/llms.txt
---

# /jobs

Step 1: Create a new job.

> 📘 Size limit
>
> We limit the number of items that can be requested in a single job to 1,000. If you want to request more than 1,000 products, you can run multiple jobs in parallel.

## JSON response

JSON response contains job information along with `job_id`, we will need it for step **2** and **3**.

## Errors

An error is indicated by an HTTP status code in the 4xx and 5xx ranges. If the error happens on an application level, we try to provide an explanation in JSON.

> 🚧 Non-JSON responses
>
> If something goes wrong somewhere deeper in our stack (say on a load balancer), we might return a different kind of response (like HTML or text).

## Example error response

```json 401 unauthorized
{
  "success": false,
  "reason": "unauthorized",
  "parameter": "token",
  "comment": "Provide your API key with the parameter 'token'!"
}
```
```html 503 service unavailable
<html><body><h1>503 Service Unavailable</h1>
No server is available to handle this request.
</body></html>
```
```json 429 Job creation limit exceeded
{
  "success": false,
  "reason": "Job creation limit exceeded",
  "comment": "You can create up to X jobs per minute."
}
```

## List of error codes

| Error code                    | Meaning                                                                                                                                                                  |
| :---------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `unauthorized`                | No `token` given or `token` is not valid.                                                                                                                                |
| `missing parameter`           | Not all required parameters were given.                                                                                                                                  |
| `parameter value invalid`     | Given `value` is not allowed for this parameter.                                                                                                                         |
| `unknown source`              | Chosen `source` is not supported (yet).                                                                                                                                  |
| `unsupported country`         | Chosen `country` is not supported for the chosen `source`.                                                                                                               |
| `unsupported key`             | Chosen `key` is not supported by the chosen `source`.                                                                                                                    |
| `source disabled`             | Combination of `source` and `country` is temporarily disabled.                                                                                                           |
| `key disabled`                | Chosen `key` is temporarily disabled for this `source` and `country`.                                                                                                    |
| `value disabled`              | Chosen `value` is temporarily disabled for this `source`, `country` and `key`.                                                                                           |
| `not enough free credits`     | Not enough free credits left for the given request, a paid subscription is needed.                                                                                       |
| `daily quota exceeded`        | User-defined daily quota is exceeded. You can change this. See [Daily quota](https://readme.priceapi.com/docs/daily-quota-doc).                                                                       |
| `too many values`             | Requested more than 1,000 `values` in one job.                                                                                                                           |
| `invalid value`               | Given `value` is not valid for the chosen `key`.                                                                                                                         |
| `no product matching`         | For the given `value` we do not have a product matching yet. For a detailed description see: [Product Matching](https://readme.priceapi.com/reference/product-matching). |
| `Job creation limit exceeded` | You have exceeded the allowed number of job creations per minute. Please wait a moment before trying again.                                                              |

Further error codes may be added.

# 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": {
      "post": {
        "summary": "/jobs",
        "description": "Step 1: Create a new job.",
        "operationId": "jobs-post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "token",
                  "source",
                  "country",
                  "topic",
                  "key",
                  "values"
                ],
                "properties": {
                  "token": {
                    "type": "string",
                    "description": "Your API key"
                  },
                  "source": {
                    "type": "string",
                    "description": "Name of the data source to request from",
                    "default": "amazon"
                  },
                  "country": {
                    "type": "string",
                    "description": "Lower case alpha-2 country code of the source to request from (like `us`, `gb`, `de`, ...)",
                    "default": "us"
                  },
                  "topic": {
                    "type": "string",
                    "description": "What type of content to collect. Different topics exist per source. (Like `search_results`, `offers`, `product`, ...",
                    "default": "product_and_offers"
                  },
                  "key": {
                    "type": "string",
                    "description": "The type of identifier you want to use. Different keys exist per topic. (`id`, `term`, `gtin`)",
                    "default": "term"
                  },
                  "values": {
                    "type": "string",
                    "description": "The identifiers you want to request, separated by newline characters",
                    "default": "apple iphone 6S 64GB gold"
                  },
                  "max_pages": {
                    "type": "string",
                    "description": "Prices may be paginated. How many pages do you want to request? Integer; default is 1.",
                    "default": "3"
                  },
                  "max_age": {
                    "type": "string",
                    "description": "How current should the data be? Give a maximum number of minutes. Integer; different defaults for each topic",
                    "default": "1440"
                  },
                  "timeout": {
                    "type": "string",
                    "description": "Number of minutes after which to stop collecting data and finishing the job. Integer; default is 1,440 minutes (24 hours).",
                    "default": "100"
                  },
                  "webhook_url": {
                    "type": "string",
                    "description": "Webhook Url will be requested once the job finishes"
                  },
                  "webhook_method": {
                    "type": "string",
                    "description": "HTTP method for initializing the webhook_url; default is POST",
                    "enum": [
                      "POST",
                      "PUT",
                      "GET"
                    ]
                  },
                  "webhook_download_format": {
                    "type": "string",
                    "description": "Defines the format of the Job result which is being generated; default format is json; not all topics support these download formats, more details can be found in the dedicated Webhooks article",
                    "enum": [
                      "json",
                      "csv",
                      "xml",
                      "xlsx"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "200",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n  \"job_id\": \"test_job_id\",\n  \"version\": \"v2\",\n  \"country\": \"us\",\n  \"source\": \"google_shopping\",\n  \"topic\": \"search_results\",\n  \"key\": \"term\",\n  \"status\": \"new\",\n  \"requested\": 1,\n  \"open_values\": 1,\n  \"free_credits\": 0,\n  \"paid_credits\": 0,\n}"
                  }
                }
              }
            }
          },
          "400": {
            "description": "400",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n  \"success\": false,\n  \"reason\": \"missing parameter\",\n  \"parameter\": \"key\",\n  \"comment\": \"Provide the mandatory parameter 'key'!\"\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": false,
                      "default": true
                    },
                    "reason": {
                      "type": "string",
                      "example": "missing parameter"
                    },
                    "parameter": {
                      "type": "string",
                      "example": "key"
                    },
                    "comment": {
                      "type": "string",
                      "example": "Provide the mandatory parameter 'key'!"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "401",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n  \"success\": false,\n  \"reason\": \"unauthorized\",\n  \"parameter\": \"token\",\n  \"comment\": \"Provide your API key with the parameter 'token'!\"\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": false,
                      "default": true
                    },
                    "reason": {
                      "type": "string",
                      "example": "unauthorized"
                    },
                    "parameter": {
                      "type": "string",
                      "example": "token"
                    },
                    "comment": {
                      "type": "string",
                      "example": "Provide your API key with the parameter 'token'!"
                    }
                  }
                }
              }
            }
          }
        },
        "x-readme": {
          "code-samples": [
            {
              "language": "curl",
              "code": "# Assuming you stored your API key in environment variable PRICEAPI_TOKEN\ncurl -X POST https://priceapi.metoda.com/v2/jobs?token=$PRICEAPI_TOKEN \\\n    -d \"source=amazon\" \\\n    -d 'country=us' \\\n    -d 'topic=product_and_offers' \\\n    -d 'key=term' \\\n    -d 'values=apple iphone 6S 64GB gold'"
            },
            {
              "language": "ruby",
              "code": "require \"net/http\"\nrequire \"json\"\n\nAPI = \"https://priceapi.metoda.com/v2\"\nENDPOINT = \"/jobs\"\nTOKEN = ENV[\"PRICEAPI_TOKEN\"]\n\nsearch_terms = [\n  \"apple iphone 6S 64GB gold\"\n]\n\njob_parameters = {\n  token: TOKEN,\n  source: \"amazon\",\n  country: \"us\",\n  topic: \"product_and_offers\",\n  key: \"term\",\n  values: search_terms.join(\"\\n\")\n}\n\nresponse = Net::HTTP.post_form(URI(API + ENDPOINT), job_parameters)\njob_id = JSON.parse(response.body)[\"job_id\"]\nputs \"Created job with id: #{job_id}\"\n\n"
            },
            {
              "language": "python",
              "code": "import json\nimport os\nfrom urllib.parse import urlencode\nfrom urllib.request import urlopen\n\nAPI = \"https://priceapi.metoda.com/v2\"\nENDPOINT = \"/jobs\"\nTOKEN = os.environ[\"PRICEAPI_TOKEN\"]\nsearch_terms = [\n  \"apple iphone 6S 64GB gold\"\n]\n\njob_parameters = {\n    \"token\": TOKEN,\n    \"source\": \"amazon\",\n    \"country\": \"us\",\n    \"topic\": \"product_and_offers\",\n    \"key\": \"term\",\n    \"values\": \"\\n\".join(search_terms)\n}\n\nresponse = urlopen(API + ENDPOINT, urlencode(job_parameters).encode())\nresult = json.loads(response.read())\njob_id = result[\"job_id\"]\nprint(\"Created job with id:\", job_id)\n"
            }
          ],
          "samples-languages": [
            "curl",
            "ruby",
            "python"
          ]
        }
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```