name: apify-api
version: v2-2026-05-28T120425Z
entrypoint: agent:ApifyApi
description: "The Apify API (version 2) provides programmatic access to the [Apify\n\
  platform](https://docs.apify.com). The API is organized\naround [RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer)\n\
  HTTP endpoints.\n\nYou can download the complete OpenAPI schema of Apify API in\
  \ the [YAML](http://docs.apify.com/api/openapi.yaml) or [JSON](http://docs.apify.com/api/openapi.json)\
  \ formats. The source code is also available on [GitHub](https://github.com/apify/apify-docs/tree/master/apify-api/openapi).\n\
  \nAll requests and responses (including errors) are encoded in\n[JSON](http://www.json.org/)\
  \ format with UTF-8 encoding,\nwith a few exceptions that are explicitly described\
  \ in the reference.\n\n- To access the API using [Node.js](https://nodejs.org/en/),\
  \ we recommend the [`apify-client`](https://docs.apify.com/api/client/js) [NPM\n\
  package](https://www.npmjs.com/package/apify-client).\n- To access the API using\
  \ [Python](https://www.python.org/), we recommend the [`apify-client`](https://docs.apify.com/api/client/python)\
  \ [PyPI\npackage](https://pypi.org/project/apify-client/).\n\nThe clients' functions\
  \ correspond to the API endpoints and have the same\nparameters. This simplifies\
  \ development of apps that depend on the Apify\nplatform.\n\n:::note Important Request\
  \ Details\n\n- `Content-Type` header: For requests with a JSON body, you must include\
  \ the `Content-Type: application/json` header.\n\n- Method override: You can override\
  \ the HTTP method using the `method` query parameter. This is useful for clients\
  \ that can only send `GET` requests. For example, to call a `POST` endpoint, append\
  \ `?method=POST` to the URL of your `GET` request.\n\n:::\n\n## Authentication\n\
  <span id=\"/introduction/authentication\"></span>\n\n**You can find your API token\
  \ on the\n[Integrations](https://console.apify.com/settings/integrations) page in\
  \ the\nApify Console.**\n\nTo use your token in a request, either:\n\n- Add the\
  \ token to your request's `Authorization` header as `Bearer <token>`.\nE.g., `Authorization:\
  \ Bearer xxxxxxx`.\n[More info](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization).\n\
  (Recommended).\n- Add it as the `token` parameter to your request URL. (Less secure).\n\
  \nUsing your token in the request header is more secure than using it as a URL\n\
  parameter because URLs are often stored\nin browser history and server logs. This\
  \ creates a chance for someone\nunauthorized to access your API token.\n\n**Never\
  \ share your API token or password with untrusted parties!**\n\nFor more information,\
  \ see our\n[integrations](https://docs.apify.com/platform/integrations) documentation.\n\
  \n## Basic usage\n<span id=\"/introduction/basic-usage\"></span>\n\nTo run an Actor,\
  \ send a POST request to the [Run\nActor](#/reference/actors/run-collection/run-actor)\
  \ endpoint using either the\nActor ID code (e.g. `vKg4IjxZbEYTYeW8T`) or its name\
  \ (e.g.\n`janedoe~my-actor`):\n\n`https://api.apify.com/v2/actors/[actor_id]/runs`\n\
  \nIf the Actor is not runnable anonymously, you will receive a 401 or 403\n[response\
  \ code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status).\nThis means you\
  \ need to add your [secret API\ntoken](https://console.apify.com/account#/integrations)\
  \ to the request's\n`Authorization` header ([recommended](#/introduction/authentication))\
  \ or as a\nURL query parameter `?token=[your_token]` (less secure).\n\nOptionally,\
  \ you can include the query parameters described in the [Run\nActor](#/reference/actors/run-collection/run-actor)\
  \ section to customize your\nrun.\n\nIf you're using Node.js, the best way to run\
  \ an Actor is using the\n`Apify.call()` method from the [Apify\nSDK](https://sdk.apify.com/docs/api/apify#apifycallactid-input-options).\
  \ It\nruns the Actor using the account you are currently logged into (determined\n\
  by the [secret API token](https://console.apify.com/account#/integrations)).\nThe\
  \ result is an [Actor run\nobject](https://sdk.apify.com/docs/typedefs/actor-run)\
  \ and its output (if\nany).\n\nA typical workflow is as follows:\n\n1. Run an Actor\
  \ or task using the [Run\nActor](#/reference/actors/run-collection/run-actor) or\
  \ [Run\ntask](#/reference/actor-tasks/run-collection/run-task) API endpoints.\n\
  2. Monitor the Actor run by periodically polling its progress using the [Get\nrun](#/reference/actor-runs/run-object-and-its-storages/get-run)\
  \ API\nendpoint.\n3. Fetch the results from the [Get\nitems](#/reference/datasets/item-collection/get-items)\
  \ API endpoint using the\n`defaultDatasetId`, which you receive in the Run request\
  \ response.\nAdditional data may be stored in a key-value store. You can fetch them\
  \ from\nthe [Get record](#/reference/key-value-stores/record/get-record) API endpoint\n\
  using the `defaultKeyValueStoreId` and the store's `key`.\n\n**Note**: Instead of\
  \ periodic polling, you can also run your\n[Actor](#/reference/actors/run-actor-synchronously)\
  \ or\n[task](#/reference/actor-tasks/runs-collection/run-task-synchronously)\nsynchronously.\
  \ This will ensure that the request waits for 300 seconds (5\nminutes) for the run\
  \ to finish and returns its output. If the run takes\nlonger, the request will time\
  \ out and throw an error.\n\n## Legacy `/v2/acts/` URL prefix\n<span id=\"/introduction/legacy-acts-prefix\"\
  ></span>\n\nThe `/v2/acts/` prefix is deprecated but still fully functional, and\
  \ \nsuch endpoint routes to the same handler as its `/v2/actors/...` counterpart.\
  \ \nNew integrations should use the canonical /v2/actors/ prefix, \nbut existing\
  \ clients keep working without changes.\n\n## Response structure\n<span id=\"/introduction/response-structure\"\
  ></span>\n\nMost API endpoints return a JSON object with the `data` property:\n\n\
  ```\n{\n    \"data\": {\n        ...\n    }\n}\n```\n\nHowever, there are a few\
  \ explicitly described exceptions, such as\n[Get dataset items](#/reference/datasets/item-collection/get-items)\
  \ or\nKey-value store [Get record](#/reference/key-value-stores/record/get-record)\n\
  API endpoints, which return data in other formats.\nIn case of an error, the response\
  \ has the HTTP status code in the range of\n4xx or 5xx and the `data` property is\
  \ replaced with `error`. For example:\n\n```\n{\n    \"error\": {\n        \"type\"\
  : \"record-not-found\",\n        \"message\": \"Store was not found.\"\n    }\n\
  }\n```\n\nSee [Errors](#/introduction/errors) for more details.\n\n## Pagination\n\
  <span id=\"/introduction/pagination\"></span>\n\nAll API endpoints that return a\
  \ list of records\n(e.g. [Get list of\nActors](#/reference/actors/actor-collection/get-list-of-actors))\n\
  enforce pagination in order to limit the size of their responses.\n\nMost of these\
  \ API endpoints are paginated using the `offset` and `limit`\nquery parameters.\n\
  The only exception is [Get list of\nkeys](#/reference/key-value-stores/key-collection/get-list-of-keys),\n\
  which is paginated using the `exclusiveStartKey` query parameter.\n\n**IMPORTANT**:\
  \ Each API endpoint that supports pagination enforces a certain\nmaximum value for\
  \ the `limit` parameter,\nin order to reduce the load on Apify servers.\nThe maximum\
  \ limit could change in future so you should never\nrely on a specific value and\
  \ check the responses of these API endpoints.\n\n### Using offset\n<span id=\"/introduction/pagination/using-offset\"\
  ></span>\n\nMost API endpoints that return a list of records enable pagination using\
  \ the\nfollowing query parameters:\n\n<table>\n  <tr>\n    <td><code>limit</code></td>\n\
  \    <td>Limits the response to contain a specific maximum number of items, e.g.\
  \ <code>limit=20</code>.</td>\n  </tr>\n  <tr>\n    <td><code>offset</code></td>\n\
  \    <td>Skips a number of items from the beginning of the list, e.g. <code>offset=100</code>.</td>\n\
  \  </tr>\n  <tr>\n    <td><code>desc</code></td>\n    <td>\n    By default, items\
  \ are sorted in the order in which they were created or added to the list.\n   \
  \ This feature is useful when fetching all the items, because it ensures that items\n\
  \    created after the client started the pagination will not be skipped.\n    If\
  \ you specify the <code>desc=1</code> parameter, the items will be returned in the\
  \ reverse order,\n    i.e. from the newest to the oldest items.\n    </td>\n  </tr>\n\
  </table>\n\nThe response of these API endpoints is always a JSON object with the\n\
  following structure:\n\n```\n{\n    \"data\": {\n        \"total\": 2560,\n    \
  \    \"offset\": 250,\n        \"limit\": 1000,\n        \"count\": 1000,\n    \
  \    \"desc\": false,\n        \"items\": [\n            { 1st object },\n     \
  \       { 2nd object },\n            ...\n            { 1000th object }\n      \
  \  ]\n    }\n}\n```\n\nThe following table describes the meaning of the response\
  \ properties:\n\n<table>\n  <tr>\n    <th>Property</th>\n    <th>Description</th>\n\
  \  </tr>\n  <tr>\n    <td><code>total</code></td>\n    <td>The total number of items\
  \ available in the list.</td>\n  </tr>\n  <tr>\n    <td><code>offset</code></td>\n\
  \    <td>The number of items that were skipped at the start.\n    This is equal\
  \ to the <code>offset</code> query parameter if it was provided, otherwise it is\
  \ <code>0</code>.</td>\n  </tr>\n  <tr>\n    <td><code>limit</code></td>\n    <td>The\
  \ maximum number of items that can be returned in the HTTP response.\n    It equals\
  \ to the <code>limit</code> query parameter if it was provided or\n    the maximum\
  \ limit enforced for the particular API endpoint, whichever is smaller.</td>\n \
  \ </tr>\n  <tr>\n    <td><code>count</code></td>\n    <td>The actual number of items\
  \ returned in the HTTP response.</td>\n  </tr>\n  <tr>\n    <td><code>desc</code></td>\n\
  \    <td><code>true</code> if data were requested in descending order and <code>false</code>\
  \ otherwise.</td>\n  </tr>\n  <tr>\n    <td><code>items</code></td>\n    <td>An\
  \ array of requested items.</td>\n  </tr>\n</table>\n\n### Using key\n<span id=\"\
  /introduction/pagination/using-key\"></span>\n\nThe records in the [key-value\n\
  store](https://docs.apify.com/platform/storage/key-value-store)\nare not ordered\
  \ based on numerical indexes,\nbut rather by their keys in the UTF-8 binary order.\n\
  Therefore the [Get list of\nkeys](#/reference/key-value-stores/key-collection/get-list-of-keys)\n\
  API endpoint only supports pagination using the following query parameters:\n\n\
  <table>\n  <tr>\n    <td><code>limit</code></td>\n    <td>Limits the response to\
  \ contain a specific maximum number items, e.g. <code>limit=20</code>.</td>\n  </tr>\n\
  \  <tr>\n    <td><code>exclusiveStartKey</code></td>\n    <td>Skips all records\
  \ with keys up to the given key including the given key,\n    in the UTF-8 binary\
  \ order.</td>\n  </tr>\n</table>\n\nThe response of the API endpoint is always a\
  \ JSON object with following\nstructure:\n\n```\n{\n    \"data\": {\n        \"\
  limit\": 1000,\n        \"isTruncated\": true,\n        \"exclusiveStartKey\": \"\
  my-key\",\n        \"nextExclusiveStartKey\": \"some-other-key\",\n        \"items\"\
  : [\n            { 1st object },\n            { 2nd object },\n            ...\n\
  \            { 1000th object }\n        ]\n    }\n}\n```\n\nThe following table\
  \ describes the meaning of the response properties:\n\n<table>\n  <tr>\n    <th>Property</th>\n\
  \    <th>Description</th>\n  </tr>\n  <tr>\n    <td><code>limit</code></td>\n  \
  \  <td>The maximum number of items that can be returned in the HTTP response.\n\
  \    It equals to the <code>limit</code> query parameter if it was provided or\n\
  \    the maximum limit enforced for the particular endpoint, whichever is smaller.</td>\n\
  \  </tr>\n  <tr>\n    <td><code>isTruncated</code></td>\n    <td><code>true</code>\
  \ if there are more items left to be queried. Otherwise <code>false</code>.</td>\n\
  \  </tr>\n  <tr>\n    <td><code>exclusiveStartKey</code></td>\n    <td>The last\
  \ key that was skipped at the start. Is `null` for the first page.</td>\n  </tr>\n\
  \  <tr>\n    <td><code>nextExclusiveStartKey</code></td>\n    <td>The value for\
  \ the <code>exclusiveStartKey</code> parameter to query the next page of items.</td>\n\
  \  </tr>\n</table>\n\n## Errors\n<span id=\"/introduction/errors\"></span>\n\nThe\
  \ Apify API uses common HTTP status codes: `2xx` range for success, `4xx`\nrange\
  \ for errors caused by the caller\n(invalid requests) and `5xx` range for server\
  \ errors (these are rare).\nEach error response contains a JSON object defining\
  \ the `error` property,\nwhich is an object with\nthe `type` and `message` properties\
  \ that contain the error code and a\nhuman-readable error description, respectively.\n\
  \nFor example:\n\n```\n{\n    \"error\": {\n        \"type\": \"record-not-found\"\
  ,\n        \"message\": \"Store was not found.\"\n    }\n}\n```\n\nHere is the table\
  \ of the most common errors that can occur for many API\nendpoints:\n\n<table>\n\
  \  <tr>\n    <th>status</th>\n    <th>type</th>\n    <th>message</th>\n  </tr>\n\
  \  <tr>\n    <td><code>400</code></td>\n    <td><code>invalid-request</code></td>\n\
  \    <td>POST data must be a JSON object</td>\n  </tr>\n  <tr>\n    <td><code>400</code></td>\n\
  \    <td><code>invalid-value</code></td>\n    <td>Invalid value provided: Comments\
  \ required</td>\n  </tr>\n  <tr>\n    <td><code>400</code></td>\n    <td><code>invalid-record-key</code></td>\n\
  \    <td>Record key contains invalid character</td>\n  </tr>\n  <tr>\n    <td><code>401</code></td>\n\
  \    <td><code>token-not-provided</code></td>\n    <td>Authentication token was\
  \ not provided</td>\n  </tr>\n  <tr>\n    <td><code>404</code></td>\n    <td><code>record-not-found</code></td>\n\
  \    <td>Store was not found</td>\n  </tr>\n  <tr>\n    <td><code>429</code></td>\n\
  \    <td><code>rate-limit-exceeded</code></td>\n    <td>You have exceeded the rate\
  \ limit of ... requests per second</td>\n  </tr>\n  <tr>\n    <td><code>405</code></td>\n\
  \    <td><code>method-not-allowed</code></td>\n    <td>This API endpoint can only\
  \ be accessed using the following HTTP methods: OPTIONS, POST</td>\n  </tr>\n</table>\n\
  \n## Rate limiting\n<span id=\"/introduction/rate-limiting\"></span>\n\nAll API\
  \ endpoints limit the rate of requests in order to prevent overloading of Apify\
  \ servers by misbehaving clients.\n\nThere are two kinds of rate limits - a global\
  \ rate limit and a per-resource rate limit.\n\n### Global rate limit\n<span id=\"\
  /introduction/rate-limiting/global-rate-limit\"></span>\n\nThe global rate limit\
  \ is set to _250 000 requests per minute_.\nFor [authenticated](#/introduction/authentication)\
  \ requests, it is counted per user,\nand for unauthenticated requests, it is counted\
  \ per IP address.\n\n### Per-resource rate limit\n<span id=\"/introduction/rate-limiting/per-resource-rate-limit\"\
  ></span>\n\nThe default per-resource rate limit is _60 requests per second per resource_,\
  \ which in this context means a single Actor, a single Actor run, a single dataset,\
  \ single key-value store etc.\nThe default rate limit is applied to every API endpoint\
  \ except a few select ones, which have higher rate limits.\nEach API endpoint returns\
  \ its rate limit in `X-RateLimit-Limit` header.\n\nThese endpoints have a rate limit\
  \ of _200 requests per second per resource_:\n\n* CRUD ([get](#/reference/key-value-stores/record/get-record),\n\
  \  [put](#/reference/key-value-stores/record/put-record),\n  [delete](#/reference/key-value-stores/record/delete-record))\n\
  \  operations on key-value store records\n\nThese endpoints have a rate limit of\
  \ _400 requests per second per resource_:\n* [Run Actor](#/reference/actors/run-collection/run-actor)\n\
  * [Run Actor task asynchronously](#/reference/actor-tasks/runs-collection/run-task-asynchronously)\n\
  * [Run Actor task synchronously](#/reference/actor-tasks/runs-collection/run-task-synchronously)\n\
  * [Metamorph Actor run](#/reference/actors/metamorph-run/metamorph-run)\n* [Push\
  \ items](#/reference/datasets/item-collection/put-items) to dataset\n* CRUD\n  ([add](#/reference/request-queues/request-collection/add-request),\n\
  \  [get](#/reference/request-queues/request-collection/get-request),\n  [update](#/reference/request-queues/request-collection/update-request),\n\
  \  [delete](#/reference/request-queues/request-collection/delete-request))\n  operations\
  \ on requests in request queues\n\n### Rate limit exceeded errors\n<span id=\"/introduction/rate-limiting/rate-limit-exceeded-errors\"\
  ></span>\n\nIf the client is sending too many requests, the API endpoints respond\
  \ with the HTTP status code `429 Too Many Requests`\nand the following body:\n\n\
  ```\n{\n    \"error\": {\n        \"type\": \"rate-limit-exceeded\",\n        \"\
  message\": \"You have exceeded the rate limit of ... requests per second\"\n   \
  \ }\n}\n```\n\n### Retrying rate-limited requests with exponential backoff\n<span\
  \ id=\"/introduction/rate-limiting/retrying-rate-limited-requests-with-exponential-backoff\"\
  ></span>\n\nIf the client receives the rate limit error, it should wait a certain\
  \ period of time and then retry the request.\nIf the error happens again, the client\
  \ should double the wait period and retry the request,\nand so on. This algorithm\
  \ is known as _exponential backoff_\nand it can be described using the following\
  \ pseudo-code:\n\n1. Define a variable `DELAY=500`\n2. Send the HTTP request to\
  \ the API endpoint\n3. If the response has status code not equal to `429` then you\
  \ are done. Otherwise:\n   * Wait for a period of time chosen randomly from the\
  \ interval `DELAY` to `2*DELAY` milliseconds\n   * Double the future wait period\
  \ by setting `DELAY = 2*DELAY`\n   * Continue with step 2\n\nIf all requests sent\
  \ by the client implement the above steps,\nthe client will automatically use the\
  \ maximum available bandwidth for its requests.\n\nNote that the Apify API clients\
  \ [for JavaScript](https://docs.apify.com/api/client/js)\nand [for Python](https://docs.apify.com/api/client/python)\n\
  use the exponential backoff algorithm transparently, so that you do not need to\
  \ worry about it.\n\n## Referring to resources\n<span id=\"/introduction/referring-to-resources\"\
  ></span>\n\nThere are three main ways to refer to a resource you're accessing via\
  \ API.\n\n- the resource ID (e.g. `iKkPcIgVvwmztduf8`)\n- `username~resourcename`\
  \ - when using this access method, you will need to\nuse your API token, and access\
  \ will only work if you have the correct\npermissions.\n- `~resourcename` - for\
  \ this, you need to use an API token, and the\n`resourcename` refers to a resource\
  \ in the API token owner's account."
runtime:
  resources:
    cpu: 200m
    memory: 512Mi
  egress:
    allow_hosts:
    - api.apify.com
    deny_internet_by_default: true