# Table of Contents - [Run Actor synchronously with input and get dataset items | Apify Documentation](#run-actor-synchronously-with-input-and-get-dataset-items-apify-documentation) - [Apify Documentation](#apify-documentation) - [Apify API | Apify Documentation](#apify-api-apify-documentation) - [API client for JavaScript | Apify Documentation](#api-client-for-javascript-apify-documentation) - [API client for Python | Apify Documentation](#api-client-for-python-apify-documentation) - [Actors - Introduction | Apify Documentation](#actors-introduction-apify-documentation) - [Create Actor | Apify Documentation](#create-actor-apify-documentation) - [Get list of Actors | Apify Documentation](#get-list-of-actors-apify-documentation) - [Get Actor | Apify Documentation](#get-actor-apify-documentation) - [Update Actor | Apify Documentation](#update-actor-apify-documentation) - [Delete Actor | Apify Documentation](#delete-actor-apify-documentation) - [Actor versions - Introduction | Apify Documentation](#actor-versions-introduction-apify-documentation) - [Get list of versions | Apify Documentation](#get-list-of-versions-apify-documentation) - [Create version | Apify Documentation](#create-version-apify-documentation) - [Get version | Apify Documentation](#get-version-apify-documentation) - [Update version | Apify Documentation](#update-version-apify-documentation) - [Delete version | Apify Documentation](#delete-version-apify-documentation) - [Get list of environment variables | Apify Documentation](#get-list-of-environment-variables-apify-documentation) - [Get environment variable | Apify Documentation](#get-environment-variable-apify-documentation) - [Update environment variable | Apify Documentation](#update-environment-variable-apify-documentation) - [Delete environment variable | Apify Documentation](#delete-environment-variable-apify-documentation) - [Create environment variable | Apify Documentation](#create-environment-variable-apify-documentation) - [Build Actor | Apify Documentation](#build-actor-apify-documentation) - [Actor builds - Introduction | Apify Documentation](#actor-builds-introduction-apify-documentation) - [Get list of builds | Apify Documentation](#get-list-of-builds-apify-documentation) - [Get default build | Apify Documentation](#get-default-build-apify-documentation) - [Get OpenAPI definition | Apify Documentation](#get-openapi-definition-apify-documentation) - [Get build | Apify Documentation](#get-build-apify-documentation) - [Get list of runs | Apify Documentation](#get-list-of-runs-apify-documentation) - [Actor runs - Introduction | Apify Documentation](#actor-runs-introduction-apify-documentation) - [Abort build | Apify Documentation](#abort-build-apify-documentation) - [Run Actor | Apify Documentation](#run-actor-apify-documentation) - [Without input | Apify Documentation](#without-input-apify-documentation) - [With input | Apify Documentation](#with-input-apify-documentation) - [Resurrect run | Apify Documentation](#resurrect-run-apify-documentation) - [Get last run | Apify Documentation](#get-last-run-apify-documentation) - [Getting started | API client for JavaScript | Apify Documentation](#getting-started-api-client-for-javascript-apify-documentation) - [Run Actor synchronously without input and get dataset items | Apify Documentation](#run-actor-synchronously-without-input-and-get-dataset-items-apify-documentation) - [Changelog | API client for JavaScript | Apify Documentation](#changelog-api-client-for-javascript-apify-documentation) - [Abort run | Apify Documentation](#abort-run-apify-documentation) - [Get run | Apify Documentation](#get-run-apify-documentation) - [Getting started | API client for JavaScript | Apify Documentation](#getting-started-api-client-for-javascript-apify-documentation) - [apify-client | API | API client for JavaScript | Apify Documentation](#apify-client-api-api-client-for-javascript-apify-documentation) - [Getting started | API client for JavaScript | Apify Documentation](#getting-started-api-client-for-javascript-apify-documentation) - [Getting started | API client for JavaScript | Apify Documentation](#getting-started-api-client-for-javascript-apify-documentation) - [Webhook collection - Introduction | Apify Documentation](#webhook-collection-introduction-apify-documentation) - [Metamorph run | Apify Documentation](#metamorph-run-apify-documentation) - [Quick start | API client for JavaScript | Apify Documentation](#quick-start-api-client-for-javascript-apify-documentation) - [Quick start | API client for JavaScript | Apify Documentation](#quick-start-api-client-for-javascript-apify-documentation) - [Get list of webhooks | Apify Documentation](#get-list-of-webhooks-apify-documentation) - [Quick start | API client for JavaScript | Apify Documentation](#quick-start-api-client-for-javascript-apify-documentation) - [Actor builds - Introduction | Apify Documentation](#actor-builds-introduction-apify-documentation) - [Get user builds list | Apify Documentation](#get-user-builds-list-apify-documentation) - [Get build | Apify Documentation](#get-build-apify-documentation) - [Delete build | Apify Documentation](#delete-build-apify-documentation) - [Abort build | Apify Documentation](#abort-build-apify-documentation) - [Get log | Apify Documentation](#get-log-apify-documentation) - [Get user runs list | Apify Documentation](#get-user-runs-list-apify-documentation) - [Actor runs - Introduction | Apify Documentation](#actor-runs-introduction-apify-documentation) - [Get OpenAPI definition | Apify Documentation](#get-openapi-definition-apify-documentation) - [Update status message | Apify Documentation](#update-status-message-apify-documentation) - [Get run | Apify Documentation](#get-run-apify-documentation) - [Delete run | Apify Documentation](#delete-run-apify-documentation) - [Metamorph run | Apify Documentation](#metamorph-run-apify-documentation) - [Abort run | Apify Documentation](#abort-run-apify-documentation) - [Reboot run | Apify Documentation](#reboot-run-apify-documentation) - [Charge events in run | Apify Documentation](#charge-events-in-run-apify-documentation) - [Resurrect run | Apify Documentation](#resurrect-run-apify-documentation) - [Actor tasks - Introduction | Apify Documentation](#actor-tasks-introduction-apify-documentation) - [Get list of tasks | Apify Documentation](#get-list-of-tasks-apify-documentation) - [Create task | Apify Documentation](#create-task-apify-documentation) - [Get task | Apify Documentation](#get-task-apify-documentation) - [Delete task | Apify Documentation](#delete-task-apify-documentation) - [Update task | Apify Documentation](#update-task-apify-documentation) - [Update task input | Apify Documentation](#update-task-input-apify-documentation) - [Get task input | Apify Documentation](#get-task-input-apify-documentation) - [Get list of task runs | Apify Documentation](#get-list-of-task-runs-apify-documentation) - [Get list of webhooks | Apify Documentation](#get-list-of-webhooks-apify-documentation) - [Run task | Apify Documentation](#run-task-apify-documentation) - [Run task synchronously | Apify Documentation](#run-task-synchronously-apify-documentation) - [Run task synchronously | Apify Documentation](#run-task-synchronously-apify-documentation) - [Run task synchronously and get dataset items | Apify Documentation](#run-task-synchronously-and-get-dataset-items-apify-documentation) - [Run task synchronously and get dataset items | Apify Documentation](#run-task-synchronously-and-get-dataset-items-apify-documentation) - [Get list of datasets | Apify Documentation](#get-list-of-datasets-apify-documentation) - [Datasets - Introduction | Apify Documentation](#datasets-introduction-apify-documentation) - [Create dataset | Apify Documentation](#create-dataset-apify-documentation) - [Get dataset | Apify Documentation](#get-dataset-apify-documentation) - [Update dataset | Apify Documentation](#update-dataset-apify-documentation) - [Delete dataset | Apify Documentation](#delete-dataset-apify-documentation) - [Key-value stores - Introduction | Apify Documentation](#key-value-stores-introduction-apify-documentation) - [Get list of key-value stores | Apify Documentation](#get-list-of-key-value-stores-apify-documentation) - [Get items | Apify Documentation](#get-items-apify-documentation) --- # Run Actor synchronously with input and get dataset items | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Run Actor synchronously with input and get dataset items ======================================================== POST /v2/acts/:actorId/run-sync-get-dataset-items -------------------------------------------- Runs a specific Actor and returns its dataset items. The POST payload including its `Content-Type` header is passed as `INPUT` to the Actor (usually `application/json`). The HTTP response contains the Actors dataset items, while the format of items depends on specifying dataset items' `format` parameter. You can send all the same options in parameters as the [Get Dataset Items](#/reference/datasets/item-collection/get-items) API endpoint. The Actor is started with the default options; you can override them using URL query parameters. If the Actor run exceeds 300 seconds, the HTTP response will return the 408 status code (Request Timeout). Beware that it might be impossible to maintain an idle HTTP connection for a long period of time, due to client timeout or network conditions. Make sure your HTTP client is configured to have a long enough connection timeout. If the connection breaks, you will not receive any information about the run and its status. To run the Actor asynchronously, use the [Run Actor](#/reference/actors/run-collection/run-actor) API endpoint instead. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 201 * 400 * 408 **Response Headers** **X-Apify-Pagination-Offset** **X-Apify-Pagination-Limit** **X-Apify-Pagination-Count** **X-Apify-Pagination-Total** **Response Headers** **Response Headers** --- # Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) API reference ------------- The Apify API allows developers to interact programmatically with apps using HTTP requests. The Apify API is built around [REST](https://en.wikipedia.org/wiki/REST) . The API has predictable resource-oriented URLs, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. [Check API reference](/api/v2) cURL # Prepare Actor input and run it synchronouslyecho '{ "searchStringsArray": ["Apify"] }' |curl -X POST -d @- \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ -L 'https://api.apify.com/v2/acts/compass~crawler-google-places/run-sync-get-dataset-items' API client ---------- The official library to interact with Apify API. ##### ![](/img/javascript-40x40.svg)![](/img/javascript-40x40.svg)JavaScript Client ##### ![](/img/python-40x40.svg)![](/img/python-40x40.svg)Python Client ### JavaScript API client The official library to interact with Apify API from a web browser, Node.js, JavaScript, or Typescript applications.[Star](https://github.com/apify/apify-client-js) [Get started](https://docs.apify.com/api/client/js/docs) [JavaScript client reference](https://docs.apify.com/api/client/js/reference) npm install apify-client // Easily run Actors, await them to finish using the convenient .call() method, and retrieve results from the resulting dataset.const { ApifyClient } = require('apify-client');const client = new ApifyClient({ token: 'MY-APIFY-TOKEN',});// Starts an actor and waits for it to finish.const { defaultDatasetId } = await client.actor('john-doe/my-cool-actor').call();// Fetches results from the actor's dataset.const { items } = await client.dataset(defaultDatasetId).listItems(); Related articles ---------------- [![](https://blog.apify.com/content/images/2022/03/vanilla-js-ice-cream-js.jpg)\ \ Web scraping with client-side Vanilla JavaScript\ \ Read more](https://blog.apify.com/web-scraping-with-client-side-vanilla-javascript/) [![](https://blog.apify.com/content/images/2021/10/python.png)\ \ Apify ❤️ Python, so we’re releasing a Python API client\ \ Read more](https://blog.apify.com/apify-python-api-client/) [![](https://blog.apify.com/content/images/2024/02/API-for-dummies.png)\ \ API for dummies\ \ Read more](https://blog.apify.com/api-for-dummies/) --- # Apify API | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) On this page Download OpenAPI * [YAML](/api/openapi.yaml) * [JSON](/api/openapi.json) Apify API ========= > **UPDATE 2025-01-14:** We have rolled out this new Apify API Documentation. In case of any issues, please [report here](https://github.com/apify/apify-docs/issues) > . The old API Documentation is still [available here](https://docs.apify.com/api/v2-old) > . The Apify API (version 2) provides programmatic access to the [Apify platform](https://docs.apify.com) . The API is organized around [RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer) HTTP endpoints. You 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) . All requests and responses (including errors) are encoded in [JSON](http://www.json.org/) format with UTF-8 encoding, with a few exceptions that are explicitly described in the reference. To access the API using [Node.js](https://nodejs.org/en/) , we recommend the [`apify-client`](https://docs.apify.com/api/client/js) [NPM package](https://www.npmjs.com/package/apify-client) . To access the API using [Python](https://www.python.org/) , we recommend the [`apify-client`](https://docs.apify.com/api/client/python) [PyPI package](https://pypi.org/project/apify-client/) . The clients' functions correspond to the API endpoints and have the same parameters. This simplifies development of apps that depend on the Apify platform. **Note:** All requests with JSON payloads need to specify the `Content-Type: application/json` HTTP header! All API endpoints support the `method` query parameter that can override the HTTP method. For example, if you want to call a POST endpoint using a GET request, simply add the query parameter `method=POST` to the URL and send the GET request. This feature is especially useful if you want to call Apify API endpoints from services that can only send GET requests. Authentication[​](#authentication "Direct link to Authentication") ------------------------------------------------------------------- You can find your API token on the [Integrations](https://console.apify.com/account#/integrations) page in the Apify Console. To use your token in a request, either: * Add the token to your request's `Authorization` header as `Bearer `. E.g., `Authorization: Bearer xxxxxxx`. [More info](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization) . (Recommended). * Add it as the `token` parameter to your request URL. (Less secure). Using your token in the request header is more secure than using it as a URL parameter because URLs are often stored in browser history and server logs. This creates a chance for someone unauthorized to access your API token. **Do not share your API token or password with untrusted parties.** For more information, see our [integrations](https://docs.apify.com/platform/integrations) documentation. Basic usage[​](#basic-usage "Direct link to Basic usage") ---------------------------------------------------------- To run an Actor, send a POST request to the [Run Actor](#/reference/actors/run-collection/run-actor) endpoint using either the Actor ID code (e.g. `vKg4IjxZbEYTYeW8T`) or its name (e.g. `janedoe~my-actor`): `https://api.apify.com/v2/acts/[actor_id]/runs` If the Actor is not runnable anonymously, you will receive a 401 or 403 [response code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) . This means you need to add your [secret API token](https://console.apify.com/account#/integrations) to the request's `Authorization` header ([recommended](#/introduction/authentication) ) or as a URL query parameter `?token=[your_token]` (less secure). Optionally, you can include the query parameters described in the [Run Actor](#/reference/actors/run-collection/run-actor) section to customize your run. If you're using Node.js, the best way to run an Actor is using the `Apify.call()` method from the [Apify SDK](https://sdk.apify.com/docs/api/apify#apifycallactid-input-options) . It runs the Actor using the account you are currently logged into (determined by the [secret API token](https://console.apify.com/account#/integrations) ). The result is an [Actor run object](https://sdk.apify.com/docs/typedefs/actor-run) and its output (if any). A typical workflow is as follows: 1. Run an Actor or task using the [Run Actor](#/reference/actors/run-collection/run-actor) or [Run task](#/reference/actor-tasks/run-collection/run-task) API endpoints. 2. Monitor the Actor run by periodically polling its progress using the [Get run](#/reference/actor-runs/run-object-and-its-storages/get-run) API endpoint. 3. Fetch the results from the [Get items](#/reference/datasets/item-collection/get-items) API endpoint using the `defaultDatasetId`, which you receive in the Run request response. Additional data may be stored in a key-value store. You can fetch them from the [Get record](#/reference/key-value-stores/record/get-record) API endpoint using the `defaultKeyValueStoreId` and the store's `key`. **Note**: Instead of periodic polling, you can also run your [Actor](#/reference/actors/run-actor-synchronously) or [task](#/reference/actor-tasks/runs-collection/run-task-synchronously) synchronously. This will ensure that the request waits for 300 seconds (5 minutes) for the run to finish and returns its output. If the run takes longer, the request will time out and throw an error. Response structure[​](#response-structure "Direct link to Response structure") ------------------------------------------------------------------------------- Most API endpoints return a JSON object with the `data` property: { "data": { ... }} However, there are a few explicitly described exceptions, such as Dataset [Get items](#/reference/datasets/item-collection/get-items) or Key-value store [Get record](#/reference/key-value-stores/record/get-record) API endpoints, which return data in other formats. In case of an error, the response has the HTTP status code in the range of 4xx or 5xx and the `data` property is replaced with `error`. For example: { "error": { "type": "record-not-found", "message": "Store was not found." }} See [Errors](#/introduction/errors) for more details. Pagination[​](#pagination "Direct link to Pagination") ------------------------------------------------------- All API endpoints that return a list of records (e.g. [Get list of Actors](#/reference/actors/actor-collection/get-list-of-actors) ) enforce pagination in order to limit the size of their responses. Most of these API endpoints are paginated using the `offset` and `limit` query parameters. The only exception is [Get list of keys](#/reference/key-value-stores/key-collection/get-list-of-keys) , which is paginated using the `exclusiveStartKey` query parameter. **IMPORTANT**: Each API endpoint that supports pagination enforces a certain maximum value for the `limit` parameter, in order to reduce the load on Apify servers. The maximum limit could change in future so you should never rely on a specific value and check the responses of these API endpoints. ### Using offset[​](#using-offset "Direct link to Using offset") Most API endpoints that return a list of records enable pagination using the following query parameters: | | | | --- | --- | | `limit` | Limits the response to contain a specific maximum number of items, e.g. `limit=20`. | | `offset` | Skips a number of items from the beginning of the list, e.g. `offset=100`. | | `desc` | By default, items are sorted in the order in which they were created or added to the list. This feature is useful when fetching all the items, because it ensures that items created after the client started the pagination will not be skipped. If you specify the `desc=1` parameter, the items will be returned in the reverse order, i.e. from the newest to the oldest items. | The response of these API endpoints is always a JSON object with the following structure: { "data": { "total": 2560, "offset": 250, "limit": 1000, "count": 1000, "desc": false, "items": [ { 1st object }, { 2nd object }, ... { 1000th object } ] }} The following table describes the meaning of the response properties: | Property | Description | | --- | --- | | `total` | The total number of items available in the list. | | `offset` | The number of items that were skipped at the start. This is equal to the `offset` query parameter if it was provided, otherwise it is `0`. | | `limit` | The maximum number of items that can be returned in the HTTP response. It equals to the `limit` query parameter if it was provided or the maximum limit enforced for the particular API endpoint, whichever is smaller. | | `count` | The actual number of items returned in the HTTP response. | | `desc` | `true` if data were requested in descending order and `false` otherwise. | | `items` | An array of requested items. | ### Using key[​](#using-key "Direct link to Using key") The records in the [key-value store](https://docs.apify.com/platform/storage/key-value-store) are not ordered based on numerical indexes, but rather by their keys in the UTF-8 binary order. Therefore the [Get list of keys](#/reference/key-value-stores/key-collection/get-list-of-keys) API endpoint only supports pagination using the following query parameters: | | | | --- | --- | | `limit` | Limits the response to contain a specific maximum number items, e.g. `limit=20`. | | `exclusiveStartKey` | Skips all records with keys up to the given key including the given key, in the UTF-8 binary order. | The response of the API endpoint is always a JSON object with following structure: { "data": { "limit": 1000, "isTruncated": true, "exclusiveStartKey": "my-key", "nextExclusiveStartKey": "some-other-key", "items": [ { 1st object }, { 2nd object }, ... { 1000th object } ] }} The following table describes the meaning of the response properties: | Property | Description | | --- | --- | | `limit` | The maximum number of items that can be returned in the HTTP response. It equals to the `limit` query parameter if it was provided or the maximum limit enforced for the particular endpoint, whichever is smaller. | | `isTruncated` | `true` if there are more items left to be queried. Otherwise `false`. | | `exclusiveStartKey` | The last key that was skipped at the start. Is `null` for the first page. | | `nextExclusiveStartKey` | The value for the `exclusiveStartKey` parameter to query the next page of items. | Errors[​](#errors "Direct link to Errors") ------------------------------------------- The Apify API uses common HTTP status codes: `2xx` range for success, `4xx` range for errors caused by the caller (invalid requests) and `5xx` range for server errors (these are rare). Each error response contains a JSON object defining the `error` property, which is an object with the `type` and `message` properties that contain the error code and a human-readable error description, respectively. For example: { "error": { "type": "record-not-found", "message": "Store was not found." }} Here is the table of the most common errors that can occur for many API endpoints: | status | type | message | | --- | --- | --- | | `400` | `invalid-request` | POST data must be a JSON object | | `400` | `invalid-value` | Invalid value provided: Comments required | | `400` | `invalid-record-key` | Record key contains invalid character | | `401` | `token-not-provided` | Authentication token was not provided | | `404` | `record-not-found` | Store was not found | | `429` | `rate-limit-exceeded` | You have exceeded the rate limit of 30 requests per second | | `405` | `method-not-allowed` | This API endpoint can only be accessed using the following HTTP methods: OPTIONS, POST | Rate limiting[​](#rate-limiting "Direct link to Rate limiting") ---------------------------------------------------------------- All API endpoints limit the rate of requests in order to prevent overloading of Apify servers by misbehaving clients. There are two kinds of rate limits - a global rate limit and a per-resource rate limit. ### Global rate limit[​](#global-rate-limit "Direct link to Global rate limit") The global rate limit is set to _250 000 requests per minute_. For [authenticated](#/introduction/authentication) requests, it is counted per user, and for unauthenticated requests, it is counted per IP address. ### Per-resource rate limit[​](#per-resource-rate-limit "Direct link to Per-resource rate limit") The default per-resource rate limit is _30 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. The default rate limit is applied to every API endpoint except a few select ones, which have higher rate limits. Each API endpoint returns its rate limit in `X-RateLimit-Limit` header. These endpoints have a rate limit of _100 requests per second per resource_: * CRUD ([get](#/reference/key-value-stores/record/get-record) , [put](#/reference/key-value-stores/record/put-record) , [delete](#/reference/key-value-stores/record/delete-record) ) operations on key-value store records These endpoints have a rate limit of _200 requests per second per resource_: * [Run Actor](#/reference/actors/run-collection/run-actor) * [Run Actor task asynchronously](#/reference/actor-tasks/runs-collection/run-task-asynchronously) * [Run Actor task synchronously](#/reference/actor-tasks/runs-collection/run-task-synchronously) * [Metamorph Actor run](#/reference/actors/metamorph-run/metamorph-run) * [Push items](#/reference/datasets/item-collection/put-items) to dataset * CRUD ([add](#/reference/request-queues/request-collection/add-request) , [get](#/reference/request-queues/request-collection/get-request) , [update](#/reference/request-queues/request-collection/update-request) , [delete](#/reference/request-queues/request-collection/delete-request) ) operations on requests in request queues ### Rate limit exceeded errors[​](#rate-limit-exceeded-errors "Direct link to Rate limit exceeded errors") If the client is sending too many requests, the API endpoints respond with the HTTP status code `429 Too Many Requests` and the following body: { "error": { "type": "rate-limit-exceeded", "message": "You have exceeded the rate limit of ... requests per second" }} ### Retrying rate-limited requests with exponential backoff[​](#retrying-rate-limited-requests-with-exponential-backoff "Direct link to Retrying rate-limited requests with exponential backoff") If the client receives the rate limit error, it should wait a certain period of time and then retry the request. If the error happens again, the client should double the wait period and retry the request, and so on. This algorithm is known as _exponential backoff_ and it can be described using the following pseudo-code: 1. Define a variable `DELAY=500` 2. Send the HTTP request to the API endpoint 3. If the response has status code not equal to `429` then you are done. Otherwise: * Wait for a period of time chosen randomly from the interval `DELAY` to `2*DELAY` milliseconds * Double the future wait period by setting `DELAY = 2*DELAY` * Continue with step 2 If all requests sent by the client implement the above steps, the client will automatically use the maximum available bandwidth for its requests. Note that the Apify API clients [for JavaScript](https://docs.apify.com/api/client/js) and [for Python](https://docs.apify.com/api/client/python) use the exponential backoff algorithm transparently, so that you do not need to worry about it. Referring to resources[​](#referring-to-resources "Direct link to Referring to resources") ------------------------------------------------------------------------------------------- There are three main ways to refer to a resource you're accessing via API. * the resource ID (e.g. `iKkPcIgVvwmztduf8`) * `username~resourcename` - when using this access method, you will need to use your API token, and access will only work if you have the correct permissions. * `~resourcename` - for this, you need to use an API token, and the `resourcename` refers to a resource in the API token owner's account. Authentication[​](#authentication "Direct link to Authentication") ------------------------------------------------------------------- * HTTP: Bearer Auth * HTTP: Bearer Auth * HTTP: Bearer Auth * HTTP: Bearer Auth * API Key: apiKey * API Key: apiKeyActorBuilds * API Key: apiKeyStoreId * API Key: apiKeyQueueId API authentication token. | | | | --- | --- | | Security Scheme Type: | http | | HTTP Authorization Scheme: | bearer | API authentication token. It is only required for private Actors. Builds of public Actors can be queried without any token. | | | | --- | --- | | Security Scheme Type: | http | | HTTP Authorization Scheme: | bearer | API authentication token. It is required only when using the `username~store-name` format for `storeId`. | | | | --- | --- | | Security Scheme Type: | http | | HTTP Authorization Scheme: | bearer | API authentication token. It is required only when using the `username~queue-name` format for `queueId`. | | | | --- | --- | | Security Scheme Type: | http | | HTTP Authorization Scheme: | bearer | API authentication token. | | | | --- | --- | | Security Scheme Type: | apiKey | | Header parameter name: | token | API authentication token. It is only required for private Actors. Builds of public Actors can be queried without any token. | | | | --- | --- | | Security Scheme Type: | apiKey | | Header parameter name: | token | API authentication token. It is required only when using the `username~store-name` format for `storeId`. | | | | --- | --- | | Security Scheme Type: | apiKey | | Header parameter name: | token | API authentication token. It is required only when using the `username~queue-name` format for `queueId`. | | | | --- | --- | | Security Scheme Type: | apiKey | | Header parameter name: | token | * [Authentication](#authentication) * [Basic usage](#basic-usage) * [Response structure](#response-structure) * [Pagination](#pagination) * [Using offset](#using-offset) * [Using key](#using-key) * [Errors](#errors) * [Rate limiting](#rate-limiting) * [Global rate limit](#global-rate-limit) * [Per-resource rate limit](#per-resource-rate-limit) * [Rate limit exceeded errors](#rate-limit-exceeded-errors) * [Retrying rate-limited requests with exponential backoff](#retrying-rate-limited-requests-with-exponential-backoff) * [Referring to resources](#referring-to-resources) --- # API client for JavaScript | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Easily run Actors, await them to finish using the convenient `.call()` method, and retrieve results from the resulting dataset. const { ApifyClient } = require('apify-client');const client = new ApifyClient({ token: 'MY-APIFY-TOKEN',});// Starts an actor and waits for it to finish.const { defaultDatasetId } = await client.actor('john-doe/my-cool-actor').call();// Fetches results from the actor's dataset.const { items } = await client.dataset(defaultDatasetId).listItems(); --- # API client for Python | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) For example, the Apify API Client for Python makes it easy to run your own Actors or Actors from the [Apify Store](https://apify.com/store) by simply using the `.call()` method to start an Actor and wait for it to finish. from apify_client import ApifyClientAsyncasync def main() -> None: apify_client = ApifyClientAsync('MY-APIFY-TOKEN') # Start an Actor and wait for it to finish. actor_client = apify_client.actor('john-doe/my-cool-actor') call_result = await actor_client.call() if call_result is None: print('Actor run failed.') return # Fetch results from the Actor run's default dataset. dataset_client = apify_client.dataset(call_result['defaultDatasetId']) list_items_result = await dataset_client.list_items() print(f'Dataset: {list_items_result}') --- # Actors - Introduction | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) The API endpoints in this section allow you to manage Apify Actors. For more details about Actors, refer to the [Actor documentation](https://docs.apify.com/platform/actors) . For API endpoints that require the `actorId` parameter to identify an Actor, you can provide either: * The Actor ID (e.g., `HG7ML7M8z78YcAPEB`), or * A tilde-separated combination of the Actor owner's username and the Actor name (e.g., `janedoe~my-actor`). [Get list of Actors\ ------------------\ \ `/acts`](/api/v2/acts-get) [Create Actor\ ------------\ \ `/acts`](/api/v2/acts-post) [Get Actor\ ---------\ \ `/acts/{actorId}`](/api/v2/act-get) [Update Actor\ ------------\ \ `/acts/{actorId}`](/api/v2/act-put) [Delete Actor\ ------------\ \ `/acts/{actorId}`](/api/v2/act-delete) --- # Create Actor | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Create Actor ============ POST /v2/acts -------- Clients[![Apify API Python Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/python.svg)](https://docs.apify.com/api/client/python/reference/class/ActorCollectionClientAsync#create) [![Apify API JavaScript Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/javascript.svg)](https://docs.apify.com/api/client/js/reference/class/ActorCollectionClient#create) Creates a new Actor with settings specified in an Actor object passed as JSON in the POST payload. The response is the full Actor object as returned by the [Get Actor](#/reference/actors/actor-object/get-actor) endpoint. The HTTP request must have the `Content-Type: application/json` HTTP header! The Actor needs to define at least one version of the source code. For more information, see [Version object](#/reference/actors/version-object) . If you want to make your Actor [public](https://docs.apify.com/platform/actors/publishing) using `isPublic: true`, you will need to provide the Actor's `title` and the `categories` under which that Actor will be classified in Apify Store. For this, it's best to use the [constants from our `apify-shared-js` package](https://github.com/apify/apify-shared-js/blob/2d43ebc41ece9ad31cd6525bd523fb86939bf860/packages/consts/src/consts.ts#L452-L471) . Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 201 **Response Headers** **Location** --- # Get list of Actors | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Get list of Actors ================== GET /v2/acts -------- Clients[![Apify API Python Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/python.svg)](https://docs.apify.com/api/client/python/reference/class/ActorCollectionClientAsync#list) [![Apify API JavaScript Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/javascript.svg)](https://docs.apify.com/api/client/js/reference/class/ActorCollectionClient#list) Gets the list of all Actors that the user created or used. The response is a list of objects, where each object contains a basic information about a single Actor. To only get Actors created by the user, add the `my=1` query parameter. The endpoint supports pagination using the `limit` and `offset` parameters and it will not return more than 1000 records. By default, the records are sorted by the `createdAt` field in ascending order, therefore you can use pagination to incrementally fetch all Actors while new ones are still being created. To sort the records in descending order, use the `desc=1` parameter. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 **Response Headers** --- # Get Actor | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Get Actor ========= GET /v2/acts/:actorId ----------------- Clients[![Apify API Python Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/python.svg)](https://docs.apify.com/api/client/python/reference/class/ActorClientAsync#get) [![Apify API JavaScript Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/javascript.svg)](https://docs.apify.com/api/client/js/reference/class/ActorClient#get) Gets an object that contains all the details about a specific Actor. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 **Response Headers** --- # Update Actor | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Update Actor ============ PUT /v2/acts/:actorId ----------------- Clients[![Apify API Python Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/python.svg)](https://docs.apify.com/api/client/python/reference/class/ActorClientAsync#update) [![Apify API JavaScript Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/javascript.svg)](https://docs.apify.com/api/client/js/reference/class/ActorClient#update) Updates settings of an Actor using values specified by an Actor object passed as JSON in the POST payload. If the object does not define a specific property, its value will not be updated. The response is the full Actor object as returned by the [Get Actor](#/reference/actors/actor-object/get-actor) endpoint. The request needs to specify the `Content-Type: application/json` HTTP header! When providing your API authentication token, we recommend using the request's `Authorization` header, rather than the URL. ([More info](#/introduction/authentication) ). If you want to make your Actor [public](https://docs.apify.com/platform/actors/publishing) using `isPublic: true`, you will need to provide the Actor's `title` and the `categories` under which that Actor will be classified in Apify Store. For this, it's best to use the [constants from our `apify-shared-js` package](https://github.com/apify/apify-shared-js/blob/2d43ebc41ece9ad31cd6525bd523fb86939bf860/packages/consts/src/consts.ts#L452-L471) . Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 **Response Headers** --- # Delete Actor | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Delete Actor ============ DELETE /v2/acts/:actorId ----------------- Clients[![Apify API JavaScript Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/javascript.svg)](https://docs.apify.com/api/client/js/reference/class/ActorClient#delete) Deletes an Actor. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 204 **Response Headers** --- # Actor versions - Introduction | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) The API endpoints in this section allow you to manage your Apify Actors versions. * The version object contains the source code of a specific version of an Actor. * The `sourceType` property indicates where the source code is hosted, and based on its value the Version object has the following additional property: | **Value** | **Description** | | --- | --- | | `"SOURCE_FILES"` | Source code is comprised of multiple files specified in the `sourceFiles` array. Each item of the array is an object with the following fields:
\- `name`: File path and name
\- `format`: Format of the content, can be either `"TEXT"` or `"BASE64"`
\- `content`: File content

Source files can be shown and edited in the Apify Console's Web IDE. | | `"GIT_REPO"` | Source code is cloned from a Git repository, whose URL is specified in the `gitRepoUrl` field. | | `"TARBALL"` | Source code is downloaded using a tarball or Zip file from a URL specified in the `tarballUrl` field. | | `"GITHUB_GIST"` | Source code is taken from a GitHub Gist, whose URL is specified in the `gitHubGistUrl` field. | For more information about source code and Actor versions, check out [Source code](https://docs.apify.com/platform/actors/development/actor-definition/source-code) in Actors documentation. [Get list of versions\ --------------------\ \ `/acts/{actorId}/versions`](/api/v2/act-versions-get) [Create version\ --------------\ \ `/acts/{actorId}/versions`](/api/v2/act-versions-post) [Get version\ -----------\ \ `/acts/{actorId}/versions/{versionNumber}`](/api/v2/act-version-get) [Update version\ --------------\ \ `/acts/{actorId}/versions/{versionNumber}`](/api/v2/act-version-put) [Delete version\ --------------\ \ `/acts/{actorId}/versions/{versionNumber}`](/api/v2/act-version-delete) [Get list of environment variables\ ---------------------------------\ \ `/acts/{actorId}/versions/{versionNumber}/env-vars`](/api/v2/act-version-env-vars-get) [Create environment variable\ ---------------------------\ \ `/acts/{actorId}/versions/{versionNumber}/env-vars`](/api/v2/act-version-env-vars-post) [Get environment variable\ ------------------------\ \ `/acts/{actorId}/versions/{versionNumber}/env-vars/{envVarName}`](/api/v2/act-version-env-var-get) [Update environment variable\ ---------------------------\ \ `/acts/{actorId}/versions/{versionNumber}/env-vars/{envVarName}`](/api/v2/act-version-env-var-put) [Delete environment variable\ ---------------------------\ \ `/acts/{actorId}/versions/{versionNumber}/env-vars/{envVarName}`](/api/v2/act-version-env-var-delete) --- # Get list of versions | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Get list of versions ==================== GET /v2/acts/:actorId/versions -------------------------- Clients[![Apify API Python Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/python.svg)](https://docs.apify.com/api/client/python/reference/class/ActorVersionCollectionClientAsync#list) Gets the list of versions of a specific Actor. The response is a JSON object with the list of [Version objects](#/reference/actors/version-object) , where each contains basic information about a single version. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 **Response Headers** --- # Create version | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Create version ============== POST /v2/acts/:actorId/versions -------------------------- Clients[![Apify API Python Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/python.svg)](https://docs.apify.com/api/client/python/reference/class/ActorVersionCollectionClientAsync#create) Creates a version of an Actor using values specified in a [Version object](#/reference/actors/version-object) passed as JSON in the POST payload. The request must specify `versionNumber` and `sourceType` parameters (as strings) in the JSON payload and a `Content-Type: application/json` HTTP header. Each `sourceType` requires its own additional properties to be passed to the JSON payload object. These are outlined in the [Version object](#/reference/actors/version-object) table below and in more detail in the [Apify documentation](https://docs.apify.com/platform/actors/development/deployment/source-types) . For example, if an Actor's source code is stored in a [GitHub repository](https://docs.apify.com/platform/actors/development/deployment/source-types#git-repository) , you will set the `sourceType` to `GIT_REPO` and pass the repository's URL in the `gitRepoUrl` property. { "versionNumber": "0.1", "sourceType": "GIT_REPO", "gitRepoUrl": "https://github.com/my-github-account/actor-repo"} The response is the [Version object](#/reference/actors/version-object) as returned by the [Get version](#/reference/actors/version-object/get-version) endpoint. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 201 **Response Headers** **Location** --- # Get version | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Get version =========== GET /v2/acts/:actorId/versions/:versionNumber ----------------------------------------- Clients[![Apify API Python Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/python.svg)](https://docs.apify.com/api/client/python/reference/class/ActorVersionClientAsync#get) Gets a [Version object](#/reference/actors/version-object) that contains all the details about a specific version of an Actor. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 **Response Headers** --- # Update version | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Update version ============== PUT /v2/acts/:actorId/versions/:versionNumber ----------------------------------------- Clients[![Apify API Python Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/python.svg)](https://docs.apify.com/api/client/python/reference/class/ActorVersionClientAsync#update) Updates Actor version using values specified by a [Version object](#/reference/actors/version-object) passed as JSON in the POST payload. If the object does not define a specific property, its value will not be updated. The request needs to specify the `Content-Type: application/json` HTTP header! When providing your API authentication token, we recommend using the request's `Authorization` header, rather than the URL. ([More info](#/introduction/authentication) ). The response is the [Version object](#/reference/actors/version-object) as returned by the [Get version](#/reference/actors/version-object/get-version) endpoint. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 **Response Headers** --- # Delete version | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Delete version ============== DELETE /v2/acts/:actorId/versions/:versionNumber ----------------------------------------- Deletes a specific version of Actor's source code. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 204 **Response Headers** --- # Get list of environment variables | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Get list of environment variables ================================= GET /v2/acts/:actorId/versions/:versionNumber/env-vars -------------------------------------------------- Clients[![Apify API Python Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/python.svg)](https://docs.apify.com/api/client/python/reference/class/ActorEnvVarCollectionClientAsync#list) Gets the list of environment variables for a specific version of an Actor. The response is a JSON object with the list of [EnvVar objects](#/reference/actors/environment-variable-object) , where each contains basic information about a single environment variable. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 **Response Headers** --- # Get environment variable | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Get environment variable ======================== GET /v2/acts/:actorId/versions/:versionNumber/env-vars/:envVarName -------------------------------------------------------------- Clients[![Apify API Python Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/python.svg)](https://docs.apify.com/api/client/python/reference/class/ActorEnvVarClientAsync#get) Gets a [EnvVar object](#/reference/actors/environment-variable-object) that contains all the details about a specific environment variable of an Actor. If `isSecret` is set to `true`, then `value` will never be returned. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 **Response Headers** --- # Update environment variable | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Update environment variable =========================== PUT /v2/acts/:actorId/versions/:versionNumber/env-vars/:envVarName -------------------------------------------------------------- Clients[![Apify API Python Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/python.svg)](https://docs.apify.com/api/client/python/reference/class/ActorEnvVarClientAsync#update) Updates Actor environment variable using values specified by a [EnvVar object](#/reference/actors/environment-variable-object) passed as JSON in the POST payload. If the object does not define a specific property, its value will not be updated. The request needs to specify the `Content-Type: application/json` HTTP header! When providing your API authentication token, we recommend using the request's `Authorization` header, rather than the URL. ([More info](#/introduction/authentication) ). The response is the [EnvVar object](#/reference/actors/environment-variable-object) as returned by the [Get environment variable](#/reference/actors/environment-variable-object/get-environment-variable) endpoint. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 **Response Headers** --- # Delete environment variable | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Delete environment variable =========================== DELETE /v2/acts/:actorId/versions/:versionNumber/env-vars/:envVarName -------------------------------------------------------------- Deletes a specific environment variable. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 204 **Response Headers** --- # Create environment variable | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Create environment variable =========================== POST /v2/acts/:actorId/versions/:versionNumber/env-vars -------------------------------------------------- Clients[![Apify API Python Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/python.svg)](https://docs.apify.com/api/client/python/reference/class/ActorEnvVarCollectionClientAsync#create) Creates an environment variable of an Actor using values specified in a [EnvVar object](#/reference/actors/environment-variable-object) passed as JSON in the POST payload. The request must specify `name` and `value` parameters (as strings) in the JSON payload and a `Content-Type: application/json` HTTP header. { "name": "ENV_VAR_NAME", "value": "my-env-var"} The response is the [EnvVar object](#/reference/actors/environment-variable-object) as returned by the [Get environment variable](#/reference/actors/environment-variable-object/get-environment-variable) endpoint. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 201 **Response Headers** **Location** --- # Build Actor | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Build Actor =========== POST /v2/acts/:actorId/builds ------------------------ Clients[![Apify API Python Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/python.svg)](https://docs.apify.com/api/client/python/reference/class/ActorClientAsync#build) [![Apify API JavaScript Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/javascript.svg)](https://docs.apify.com/api/client/js/reference/class/ActorClient#build) Builds an Actor. The response is the build object as returned by the [Get build](#/reference/actors/build-object/get-build) endpoint. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 201 **Response Headers** **Location** --- # Actor builds - Introduction | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) The API endpoints in this section allow you to manage your Apify Actors builds. [Get list of builds\ ------------------\ \ `/acts/{actorId}/builds`](/api/v2/act-builds-get) [Build Actor\ -----------\ \ `/acts/{actorId}/builds`](/api/v2/act-builds-post) [Get default build\ -----------------\ \ `/acts/{actorId}/builds/default`](/api/v2/act-build-default-get) [Get OpenAPI definition\ ----------------------\ \ `/acts/{actorId}/builds/{buildId}/openapi.json`](/api/v2/act-openapi-json-get) [Get build\ ---------\ \ `/acts/{actorId}/builds/{buildId}`](/api/v2/act-build-get) [Abort build\ -----------\ \ `/acts/{actorId}/builds/{buildId}/abort`](/api/v2/act-build-abort-post) --- # Get list of builds | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Get list of builds ================== GET /v2/acts/:actorId/builds ------------------------ Clients[![Apify API Python Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/python.svg)](https://docs.apify.com/api/client/python/reference/class/BuildCollectionClientAsync#list) [![Apify API JavaScript Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/javascript.svg)](https://docs.apify.com/api/client/js/reference/class/BuildCollectionClient#list) Gets the list of builds of a specific Actor. The response is a JSON with the list of objects, where each object contains basic information about a single build. The endpoint supports pagination using the `limit` and `offset` parameters and it will not return more than 1000 records. By default, the records are sorted by the `startedAt` field in ascending order, therefore you can use pagination to incrementally fetch all builds while new ones are still being started. To sort the records in descending order, use the `desc=1` parameter. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 **Response Headers** --- # Get default build | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Get default build ================= GET /v2/acts/:actorId/builds/default -------------------------------- Get the default build for an Actor. Use the optional `waitForFinish` parameter to synchronously wait for the build to finish. This avoids the need for periodic polling when waiting for the build to complete. This endpoint does not require an authentication token. Instead, calls are authenticated using the build's unique ID. However, if you access the endpoint without a token, certain attributes (e.g., `usageUsd` and `usageTotalUsd`) will be hidden. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 **Response Headers** --- # Get OpenAPI definition | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Get OpenAPI definition ====================== GET /v2/acts/:actorId/builds/:buildId/openapi.json ---------------------------------------------- Get the OpenAPI definition for Actor builds. Two similar endpoints are available: * [First endpoint](/api/v2/act-openapi-json-get) : Requires both `actorId` and `buildId`. Use `default` as the `buildId` to get the OpenAPI schema for the default Actor build. * [Second endpoint](/api/v2/actor-build-openapi-json-get) : Requires only `buildId`. Get the OpenAPI definition for a specific Actor build. To fetch the default Actor build, simply pass `default` as the `buildId`. Authentication is based on the build's unique ID. No authentication token is required. note You can also use the [`/api/v2/actor-build-openapi-json-get`](/api/v2/actor-build-openapi-json-get) endpoint to get the OpenAPI definition for a build. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 **Response Headers** --- # Get build | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Get build ========= GET /v2/acts/:actorId/builds/:buildId --------------------------------- deprecated API endpoints related to build of the Actor were moved under new namespace [`actor-builds`](#/reference/actor-builds) . Gets an object that contains all the details about a specific build of an Actor. By passing the optional `waitForFinish` parameter the API endpoint will synchronously wait for the build to finish. This is useful to avoid periodic polling when waiting for an Actor build to finish. This endpoint does not require the authentication token. Instead, calls are authenticated using a hard-to-guess ID of the build. However, if you access the endpoint without the token, certain attributes, such as `usageUsd` and `usageTotalUsd`, will be hidden. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 **Response Headers** --- # Get list of runs | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Get list of runs ================ GET /v2/acts/:actorId/runs ---------------------- Clients[![Apify API Python Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/python.svg)](https://docs.apify.com/api/client/python/reference/class/RunCollectionClientAsync#list) [![Apify API JavaScript Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/javascript.svg)](https://docs.apify.com/api/client/js/reference/class/RunCollectionClient#list) Gets the list of runs of a specific Actor. The response is a list of objects, where each object contains basic information about a single Actor run. The endpoint supports pagination using the `limit` and `offset` parameters and it will not return more than 1000 array elements. By default, the records are sorted by the `startedAt` field in ascending order, therefore you can use pagination to incrementally fetch all records while new ones are still being created. To sort the records in descending order, use `desc=1` parameter. You can also filter runs by status ([available statuses](https://docs.apify.com/platform/actors/running/runs-and-builds#lifecycle) ). Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 **Response Headers** --- # Actor runs - Introduction | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) The API endpoints in this section allow you to manage your Apify Actors runs. Some API endpoints return run objects. If a run object includes usage costs in dollars, note that these values are calculated based on your effective unit pricing at the time of the query. As a result, the dollar amounts should be treated as informational only and not as exact figures. For more information about platform usage and resource calculations, see the [Usage and Resources documentation](https://docs.apify.com/platform/actors/running/usage-and-resources#usage) . [Get list of runs\ ----------------\ \ `/acts/{actorId}/runs`](/api/v2/act-runs-get) [Run Actor\ ---------\ \ `/acts/{actorId}/runs`](/api/v2/act-runs-post) [With input\ ----------\ \ `/acts/{actorId}/run-sync`](/api/v2/act-run-sync-post) [Without input\ -------------\ \ `/acts/{actorId}/run-sync`](/api/v2/act-run-sync-get) [Run Actor synchronously with input and get dataset items\ --------------------------------------------------------\ \ `/acts/{actorId}/run-sync-get-dataset-items`](/api/v2/act-run-sync-get-dataset-items-post) [Run Actor synchronously without input and get dataset items\ -----------------------------------------------------------\ \ `/acts/{actorId}/run-sync-get-dataset-items`](/api/v2/act-run-sync-get-dataset-items-get) [Resurrect run\ -------------\ \ `/acts/{actorId}/runs/{runId}/resurrect`](/api/v2/act-run-resurrect-post) [Get last run\ ------------\ \ `/acts/{actorId}/runs/last`](/api/v2/act-runs-last-get) [Get run\ -------\ \ `/acts/{actorId}/runs/{runId}`](/api/v2/act-run-get) [Abort run\ ---------\ \ `/acts/{actorId}/runs/{runId}/abort`](/api/v2/act-run-abort-post) [Metamorph run\ -------------\ \ `/acts/{actorId}/runs/{runId}/metamorph`](/api/v2/act-run-metamorph-post) --- # Abort build | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Abort build =========== POST /v2/acts/:actorId/builds/:buildId/abort --------------------------------------- deprecated This endpoint has been deprecated and may be replaced or removed in future versions of the API. **\[DEPRECATED\]** API endpoints related to build of the Actor were moved under new namespace [`actor-builds`](#/reference/actor-builds) . Aborts an Actor build and returns an object that contains all the details about the build. Only builds that are starting or running are aborted. For builds with status `FINISHED`, `FAILED`, `ABORTING` and `TIMED-OUT` this call does nothing. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 **Response Headers** --- # Run Actor | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Run Actor ========= POST /v2/acts/:actorId/runs ---------------------- Clients[![Apify API Python Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/python.svg)](https://docs.apify.com/api/client/python/reference/class/ActorClientAsync#call) [![Apify API JavaScript Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/javascript.svg)](https://docs.apify.com/api/client/js/reference/class/ActorClient#start) Runs an Actor and immediately returns without waiting for the run to finish. The POST payload including its `Content-Type` header is passed as `INPUT` to the Actor (usually `application/json`). The Actor is started with the default options; you can override them using various URL query parameters. The response is the Run object as returned by the [Get run](#/reference/actor-runs/run-object-and-its-storages/get-run) API endpoint. If you want to wait for the run to finish and receive the actual output of the Actor as the response, please use one of the [Run Actor synchronously](#/reference/actors/run-actor-synchronously) API endpoints instead. To fetch the Actor run results that are typically stored in the default dataset, you'll need to pass the ID received in the `defaultDatasetId` field received in the response JSON to the [Get items](#/reference/datasets/item-collection/get-items) API endpoint. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 201 **Response Headers** **Location** --- # Without input | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Without input ============= GET /v2/acts/:actorId/run-sync -------------------------- Runs a specific Actor and returns its output. The run must finish in 300 seconds otherwise the API endpoint returns a timeout error. The Actor is not passed any input. Beware that it might be impossible to maintain an idle HTTP connection for a long period of time, due to client timeout or network conditions. Make sure your HTTP client is configured to have a long enough connection timeout. If the connection breaks, you will not receive any information about the run and its status. To run the Actor asynchronously, use the [Run Actor](#/reference/actors/run-collection/run-actor) API endpoint instead. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 201 * 400 * 408 **Response Headers** **Response Headers** **Response Headers** --- # With input | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) With input ========== POST /v2/acts/:actorId/run-sync -------------------------- Runs a specific Actor and returns its output. The POST payload including its `Content-Type` header is passed as `INPUT` to the Actor (usually `application/json`). The HTTP response contains Actors `OUTPUT` record from its default key-value store. The Actor is started with the default options; you can override them using various URL query parameters. If the Actor run exceeds 300 seconds, the HTTP response will have status 408 (Request Timeout). Beware that it might be impossible to maintain an idle HTTP connection for a long period of time, due to client timeout or network conditions. Make sure your HTTP client is configured to have a long enough connection timeout. If the connection breaks, you will not receive any information about the run and its status. To run the Actor asynchronously, use the [Run Actor](#/reference/actors/run-collection/run-actor) API endpoint instead. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 201 * 400 * 408 **Response Headers** **Response Headers** **Response Headers** --- # Resurrect run | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Resurrect run ============= POST /v2/acts/:actorId/runs/:runId/resurrect --------------------------------------- **\[DEPRECATED\]** API endpoints related to run of the Actor were moved under new namespace [`actor-runs`](#/reference/actor-runs) .Resurrects a finished Actor run and returns an object that contains all the details about the resurrected run. Only finished runs, i.e. runs with status `FINISHED`, `FAILED`, `ABORTED` and `TIMED-OUT` can be resurrected. Run status will be updated to RUNNING and its container will be restarted with the same storages (the same behaviour as when the run gets migrated to the new server). For more information, see the [Actor docs](https://docs.apify.com/platform/actors/running/runs-and-builds#resurrection-of-finished-run) . Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 **Response Headers** --- # Get last run | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Get last run ============ GET /v2/acts/:actorId/runs/last --------------------------- This is not a single endpoint, but an entire group of endpoints that lets you to retrieve and manage the last run of given Actor or any of its default storages. All the endpoints require an authentication token. The endpoints accept the same HTTP methods and query parameters as the respective storage endpoints. The base path represents the last Actor run object is: `/v2/acts/{actorId}/runs/last{?token,status}` Using the `status` query parameter you can ensure to only get a run with a certain status (e.g. `status=SUCCEEDED`). The output of this endpoint and other query parameters are the same as in the [Run object](#/reference/actors/run-object) endpoint. In order to access the default storages of the last Actor run, i.e. log, key-value store, dataset and request queue, use the following endpoints: * `/v2/acts/{actorId}/runs/last/log{?token,status}` * `/v2/acts/{actorId}/runs/last/key-value-store{?token,status}` * `/v2/acts/{actorId}/runs/last/dataset{?token,status}` * `/v2/acts/{actorId}/runs/last/request-queue{?token,status}` These API endpoints have the same usage as the equivalent storage endpoints. For example, `/v2/acts/{actorId}/runs/last/key-value-store` has the same HTTP method and parameters as the [Key-value store object](#/reference/key-value-stores/store-object) endpoint. Additionally, each of the above API endpoints supports all sub-endpoints of the original one: #### Key-value store[​](#key-value-store "Direct link to Key-value store") * `/v2/acts/{actorId}/runs/last/key-value-store/keys{?token,status}` [Key collection](#/reference/key-value-stores/key-collection) * `/v2/acts/{actorId}/runs/last/key-value-store/records/{recordKey}{?token,status}` [Record](#/reference/key-value-stores/record) #### Dataset[​](#dataset "Direct link to Dataset") * `/v2/acts/{actorId}/runs/last/dataset/items{?token,status}` [Item collection](#/reference/datasets/item-collection) #### Request queue[​](#request-queue "Direct link to Request queue") * `/v2/acts/{actorId}/runs/last/request-queue/requests{?token,status}` [Request collection](#/reference/request-queues/request-collection) * `/v2/acts/{actorId}/runs/last/request-queue/requests/{requestId}{?token,status}` [Request collection](#/reference/request-queues/request) * `/v2/acts/{actorId}/runs/last/request-queue/head{?token,status}` [Queue head](#/reference/request-queues/queue-head) For example, to download data from a dataset of the last succeeded Actor run in XML format, send HTTP GET request to the following URL: https://api.apify.com/v2/acts/{actorId}/runs/last/dataset/items?token={yourApiToken}&format=xml&status=SUCCEEDED In order to save new items to the dataset, send HTTP POST request with JSON payload to the same URL. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 **Response Headers** --- # Getting started | API client for JavaScript | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Version: 2.11 On this page `apify-client` is the official library to access the [Apify REST API](https://docs.apify.com/api/v2) from your JavaScript/TypeScript applications. It runs both in Node.js and browser and provides useful features like automatic retries and convenience functions that improve the experience of using the Apify API. All requests and responses (including errors) are encoded in JSON format with UTF-8 encoding. Pre-requisites[​](#pre-requisites "Direct link to heading") ------------------------------------------------------------ `apify-client` requires Node.js version 16 or higher. Node.js is available for download on the [official website](https://nodejs.org/) . Check for your current node version by running: node -v Installation[​](#installation "Direct link to heading") -------------------------------------------------------- You can install the client via [NPM](https://www.npmjs.com/) or use any other package manager of your choice. * NPM * Yarn * PNPM * Bun npm i apify-client yarn add apify-client pnpm add apify-client bun add apify-client Authentication and Initialization[​](#authentication-and-initialization "Direct link to heading") -------------------------------------------------------------------------------------------------- To use the client, you need an [API token](https://docs.apify.com/platform/integrations/api#api-token) . You can find your token under [Integrations](https://console.apify.com/account/integrations) tab in Apify Console. Copy the token and initialize the client by providing the token (`MY-APIFY-TOKEN`) as a parameter to the `ApifyClient` constructor. // import Apify clientimport { ApifyClient } from 'apify-client';// Client initialization with the API tokenconst client = new ApifyClient({ token: 'MY-APIFY-TOKEN',}); Secure access The API token is used to authorize your requests to the Apify API. You can be charged for the usage of the underlying services, so do not share your API token with untrusted parties or expose it on the client side of your applications Quick start[​](#quick-start "Direct link to heading") ------------------------------------------------------ One of the most common use cases is starting [Actors](https://docs.apify.com/platform/actors) (serverless programs running in the [Apify cloud](https://docs.apify.com/platform) ) and getting results from their [datasets](https://docs.apify.com/platform/storage/dataset) (storage) after they finish the job (usually scraping, automation processes or data processing). import { ApifyClient } from 'apify-client';const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });// Starts an Actor and waits for it to finishconst { defaultDatasetId } = await client.actor('username/actor-name').call();// Lists items from the Actor's datasetconst { items } = await client.dataset(defaultDatasetId).listItems(); ### Running Actors[​](#running-actors "Direct link to heading") To start an Actor, you can use the [ActorClient](/api/client/js/reference/class/ActorClient) (`client.actor()`) and pass the Actor's ID (e.g. `john-doe/my-cool-actor`) to define which Actor you want to run. The Actor's ID is a combination of the username and the Actor owner’s username. You can run both your own Actors and [Actors from Apify Store](https://docs.apify.com/platform/actors/running/actors-in-store) . #### Passing input to the Actor[​](#passing-input-to-the-actor "Direct link to heading") To define the Actor's input, you can pass an object to the [`call()`](/api/client/js/reference/class/ActorClient#call) method. The input object can be any JSON object that the Actor expects (respects the Actor's [input schema](https://docs.apify.com/platform/actors/development/actor-definition/input-schema) ). The input object is used to pass configuration to the Actor, such as URLs to scrape, search terms, or any other data. import { ApifyClient } from 'apify-client';const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });// Runs an Actor with an input and waits for it to finish.const { defaultDatasetId } = await client.actor('username/actor-name').call({ some: 'input',}); ### Getting results from the dataset[​](#getting-results-from-the-dataset "Direct link to heading") To get the results from the dataset, you can use the [DatasetClient](/api/client/js/reference/class/DatasetClient) (`client.dataset()`) and [`listItems()`](/api/client/js/reference/class/DatasetClient#listItems) method. You need to pass the dataset ID to define which dataset you want to access. You can get the dataset ID from the Actor's run object (represented by `defaultDatasetId`). import { ApifyClient } from 'apify-client';const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });// Lists items from the Actor's dataset.const { items } = await client.dataset('dataset-id').listItems(); Dataset access Running an Actor might take time, depending on the Actor's complexity and the amount of data it processes. If you want only to get data and have an immediate response you should access the existing dataset of the finished [Actor run](https://docs.apify.com/platform/actors/running/runs-and-builds#runs) . Usage concepts[​](#usage-concepts "Direct link to heading") ------------------------------------------------------------ The `ApifyClient` interface follows a generic pattern that applies to all of its components. By calling individual methods of `ApifyClient`, specific clients that target individual API resources are created. There are two types of those clients: * [`actorClient`](/api/client/js/reference/class/ActorClient) : a client for the management of a single resource * [`actorCollectionClient`](/api/client/js/reference/class/ActorCollectionClient) : a client for the collection of resources import { ApifyClient } from 'apify-client';const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });// Collection clients do not require a parameter.const actorCollectionClient = client.actors();// Creates an actor with the name: my-actor.const myActor = await actorCollectionClient.create({ name: 'my-actor-name' });// List all your used Actors (both own and from Apify Store)const { items } = await actorCollectionClient.list(); Resource identification The resource ID can be either the `id` of the said resource, or a combination of your `username/resource-name`. import { ApifyClient } from 'apify-client';const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });// Resource clients accept an ID of the resource.const actorClient = client.actor('username/actor-name');// Fetches the john-doe/my-actor object from the API.const myActor = await actorClient.get();// Starts the run of john-doe/my-actor and returns the Run object.const myActorRun = await actorClient.start(); ### Nested clients[​](#nested-clients "Direct link to heading") Sometimes clients return other clients. That's to simplify working with nested collections, such as runs of a given Actor. import { ApifyClient } from 'apify-client';const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });const actorClient = client.actor('username/actor-name');const runsClient = actorClient.runs();// Lists the last 10 runs of your Actor.const { items } = await runsClient.list({ limit: 10, desc: true});// Select the last run of your Actor that finished// with a SUCCEEDED status.const lastSucceededRunClient = actorClient.lastRun({ status: 'SUCCEEDED' });// Fetches items from the run's dataset.const { items } = await lastSucceededRunClient.dataset() .listItems(); The quick access to `dataset` and other storage directly from the run client can be used with the [`lastRun()`](/api/client/js/reference/class/ActorClient#lastRun)  method. Features[​](#features "Direct link to heading") ------------------------------------------------ Based on the endpoint, the client automatically extracts the relevant data and returns it in the expected format. Date strings are automatically converted to `Date` objects. For exceptions, the client throws an [`ApifyApiError`](/api/client/js/reference/class/ApifyApiError) , which wraps the plain JSON errors returned by API and enriches them with other contexts for easier debugging. import { ApifyClient } from 'apify-client';const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });try { const { items } = await client.dataset("non-existing-dataset-id").listItems();} catch (error) { // The error is an instance of ApifyApiError const { message, type, statusCode, clientMethod, path } = error; // Log error for easier debugging console.log({ message, statusCode, clientMethod, type });} ### Retries with exponential backoff[​](#retries-with-exponential-backoff "Direct link to heading") Network communication sometimes fails. That's a given. The client will automatically retry requests that failed due to a network error, an internal error of the Apify API (HTTP 500+), or a rate limit error (HTTP 429). By default, it will retry up to 8 times. The first retry will be attempted after ~500ms, the second after ~1000ms, and so on. You can configure those parameters using the `maxRetries` and `minDelayBetweenRetriesMillis` options of the `ApifyClient` constructor. import { ApifyClient } from 'apify-client';const client = new ApifyClient({ token: 'MY-APIFY-TOKEN', maxRetries: 8, minDelayBetweenRetriesMillis: 500, // 0.5s timeoutSecs: 360 // 6 mins}); ### Convenience functions and options[​](#convenience-functions-and-options "Direct link to heading") Some actions can't be performed by the API itself, such as indefinite waiting for an Actor run to finish (because of network timeouts). The client provides convenient `call()` and `waitForFinish()` functions that do that. If the limit is reached, the returned promise is resolved to a run object that will have status `READY` or `RUNNING` and it will not contain the Actor run output. [Key-value store](https://docs.apify.com/platform/storage/key-value-store) records can be retrieved as objects, buffers, or streams via the respective options, dataset items can be fetched as individual objects or serialized data. import { ApifyClient } from 'apify-client';const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });// Starts an Actor and waits for it to finish.const finishedActorRun = await client.actor('username/actor-name').call();// Starts an Actor and waits maximum 60s for the finish const { status } = await client.actor('username/actor-name').start({ waitForFinish: 60, // 1 minute}); ### Pagination[​](#pagination "Direct link to heading") Most methods named `list` or `listSomething` return a [`Promise`](/api/client/js/reference/interface/PaginatedList) . There are some exceptions though, like `listKeys` or `listHead` which paginate differently. The results you're looking for are always stored under `items` and you can use the `limit` property to get only a subset of results. Other props are also available, depending on the method. import { ApifyClient } from 'apify-client';const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });// Resource clients accept an ID of the resource.const datasetClient = client.dataset('dataset-id');// Number of items per pageconst limit = 1000;// Initial offsetlet offset = 0; // Array to store all itemslet allItems = []; while (true) { const { items, total } = await datasetClient.listItems({ limit, offset }); console.log(`Fetched ${items.length} items`); // Merge new items with other already loaded items allItems.push(...items); // If there are no more items to fetch, exit the loading if (offset + limit >= total) { break; } offset += limit;}console.log(`Overall fetched ${allItems.length} items`); * [Pre-requisites](#pre-requisites) * [Installation](#installation) * [Authentication and Initialization](#authentication-and-initialization) * [Quick start](#quick-start) * [Running Actors](#running-actors) * [Getting results from the dataset](#getting-results-from-the-dataset) * [Usage concepts](#usage-concepts) * [Nested clients](#nested-clients) * [Features](#features) * [Retries with exponential backoff](#retries-with-exponential-backoff) * [Convenience functions and options](#convenience-functions-and-options) * [Pagination](#pagination) --- # Run Actor synchronously without input and get dataset items | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Run Actor synchronously without input and get dataset items =========================================================== GET /v2/acts/:actorId/run-sync-get-dataset-items -------------------------------------------- Runs a specific Actor and returns its dataset items. The run must finish in 300 seconds otherwise the API endpoint returns a timeout error. The Actor is not passed any input. It allows to send all possible options in parameters from [Get Dataset Items](#/reference/datasets/item-collection/get-items) API endpoint. Beware that it might be impossible to maintain an idle HTTP connection for a long period of time, due to client timeout or network conditions. Make sure your HTTP client is configured to have a long enough connection timeout. If the connection breaks, you will not receive any information about the run and its status. To run the Actor asynchronously, use the [Run Actor](#/reference/actors/run-collection/run-actor) API endpoint instead. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 201 * 400 * 408 **Response Headers** **X-Apify-Pagination-Offset** **X-Apify-Pagination-Limit** **X-Apify-Pagination-Count** **X-Apify-Pagination-Total** **Response Headers** **Response Headers** --- # Changelog | API client for JavaScript | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Version: 2.11 On this page ### [2.11.2](https://github.com/apify/apify-client-js/releases/tag/v2.11.2) [​](#2112 "Direct link to heading") ##### [2.11.2](https://github.com/apify/apify-client-js/releases/tag/v2.11.2) (2025-02-03)[​](#2112-2025-02-03 "Direct link to heading") ###### 🚀 Features[​](#-features "Direct link to heading") * Add dataset.statistics ([#621](https://github.com/apify/apify-client-js/pull/621) ) ([6aeb2b7](https://github.com/apify/apify-client-js/commit/6aeb2b7fae041468d125a0c8bbb00804e290143a) ) by [@MFori](https://github.com/MFori) * Added getOpenApiSpecification() to BuildClient ([#626](https://github.com/apify/apify-client-js/pull/626) ) ([6248b28](https://github.com/apify/apify-client-js/commit/6248b2844796f93e22404ddea85ee77c1a5b7d50) ) by [@danpoletaev](https://github.com/danpoletaev) ### [2.11.1](https://github.com/apify/apify-client-js/releases/tag/v2.11.1) [​](#2111 "Direct link to heading") ##### [2.11.1](https://github.com/apify/apify-client-js/releases/tag/v2.11.1) (2025-01-10)[​](#2111-2025-01-10 "Direct link to heading") ###### 🐛 Bug Fixes[​](#-bug-fixes "Direct link to heading") * Change type `Build.actorDefinitions` to `Build.actorDefinition` ([#624](https://github.com/apify/apify-client-js/pull/624) ) ([611f313](https://github.com/apify/apify-client-js/commit/611f31365727e70f58d899009ff5a05c6b888253) ) by [@jirispilka](https://github.com/jirispilka) * Add ActorRunPricingInfo type ([#623](https://github.com/apify/apify-client-js/pull/623) ) ([8880295](https://github.com/apify/apify-client-js/commit/8880295f13c1664ab6ae0b8b3f171025317ea011) ) by [@janbuchar](https://github.com/janbuchar) ### [2.11.0](https://github.com/apify/apify-client-js/releases/tag/v2.11.0) [​](#2110 "Direct link to heading") ##### [2.11.0](https://github.com/apify/apify-client-js/releases/tag/v2.11.0) (2024-12-16)[​](#2110-2024-12-16 "Direct link to heading") ###### 🚀 Features[​](#-features-1 "Direct link to heading") * **actor-build:** Add actorDefinition type for actor build detail, deprecate inputSchema and readme. ([#611](https://github.com/apify/apify-client-js/pull/611) ) ([123c2b8](https://github.com/apify/apify-client-js/commit/123c2b81c945a0ca6922221598aa73c42cc298d6) ) by [@drobnikj](https://github.com/drobnikj) * Add `charge` method to the run client for "pay per event" ([#613](https://github.com/apify/apify-client-js/pull/613) ) ([3d9c64d](https://github.com/apify/apify-client-js/commit/3d9c64d5442b4f8f27c2b19dd98dd3b758944287) ) by [@Jkuzz](https://github.com/Jkuzz) * **request-queue:** Add queueHasLockedRequests and clientKey into RequestQueueClientListAndLockHeadResult ([#617](https://github.com/apify/apify-client-js/pull/617) ) ([f58ce98](https://github.com/apify/apify-client-js/commit/f58ce989e431de54eb673e561e407a7066ea2b64) ) by [@drobnikj](https://github.com/drobnikj) ###### 🐛 Bug Fixes[​](#-bug-fixes-1 "Direct link to heading") * **actor:** Correctly set type for ActorTaggedBuilds ([#612](https://github.com/apify/apify-client-js/pull/612) ) ([3bda7ee](https://github.com/apify/apify-client-js/commit/3bda7ee741caf2ccfea249a42ed7512cda36bf0b) ) by [@metalwarrior665](https://github.com/metalwarrior665) ### [2.10.0](https://github.com/apify/apify-client-js/releases/tag/v2.10.0) [​](#2100 "Direct link to heading") ##### [2.10.0](https://github.com/apify/apify-client-js/releases/tag/v2.10.0) (2024-11-01)[​](#2100-2024-11-01 "Direct link to heading") ###### 🚀 Features[​](#-features-2 "Direct link to heading") * Add user.updateLimits ([#595](https://github.com/apify/apify-client-js/pull/595) ) ([bf97c0f](https://github.com/apify/apify-client-js/commit/bf97c0f5bf8d0cbd8decb60382f0605243b00dd5) ) by [@MFori](https://github.com/MFori) * Allow appending custom parts to the user agent ([#602](https://github.com/apify/apify-client-js/pull/602) ) ([d07452b](https://github.com/apify/apify-client-js/commit/d07452b7bff83d16b48bf3cfba5b88aa564ffe2b) ) by [@B4nan](https://github.com/B4nan) ###### 🐛 Bug Fixes[​](#-bug-fixes-2 "Direct link to heading") * Allow `null` when updating dataset/kvs/rq `name` ([#604](https://github.com/apify/apify-client-js/pull/604) ) ([0034c2e](https://github.com/apify/apify-client-js/commit/0034c2ee63d6d1c6856c4e7786da43d86a3d63ce) ) by [@B4nan](https://github.com/B4nan) ### [v2.9.7](https://github.com/apify/apify-client-js/releases/tag/v2.9.7) [​](#v297 "Direct link to heading") ##### What's Changed[​](#whats-changed "Direct link to heading") * feat: Rename maxCostPerRunUsd to maxTotalChargeUsd by [@novotnyj](https://github.com/novotnyj) in [#592](https://github.com/apify/apify-client-js/pull/592) **Full Changelog**: [https://github.com/apify/apify-client-js/compare/v2.9.6...v2.9.7](https://github.com/apify/apify-client-js/compare/v2.9.6...v2.9.7) ### [v2.9.6](https://github.com/apify/apify-client-js/releases/tag/v2.9.6) [​](#v296 "Direct link to heading") ##### What's Changed[​](#whats-changed-1 "Direct link to heading") * fix: Rename maxCostPerRun by [@novotnyj](https://github.com/novotnyj) in [#589](https://github.com/apify/apify-client-js/pull/589) **Full Changelog**: [https://github.com/apify/apify-client-js/compare/v2.9.5...v2.9.6](https://github.com/apify/apify-client-js/compare/v2.9.5...v2.9.6) ### [v2.9.5](https://github.com/apify/apify-client-js/releases/tag/v2.9.5) [​](#v295 "Direct link to heading") ##### What's Changed[​](#whats-changed-2 "Direct link to heading") * fix: add `isDeprecated` to actor update type by [@Jkuzz](https://github.com/Jkuzz) in [#566](https://github.com/apify/apify-client-js/pull/566) * feat: add Actor Standby types by [@jirimoravcik](https://github.com/jirimoravcik) in [#569](https://github.com/apify/apify-client-js/pull/569) * feat: allow `unwind` param to `DatasetClient.listItems()` to be an array by [@fnesveda](https://github.com/fnesveda) in [#576](https://github.com/apify/apify-client-js/pull/576) * feat: add maxCostPerRun param by [@stetizu1](https://github.com/stetizu1) in [#578](https://github.com/apify/apify-client-js/pull/578) ##### New Contributors[​](#new-contributors "Direct link to heading") * [@stetizu1](https://github.com/stetizu1) made their first contribution in [#578](https://github.com/apify/apify-client-js/pull/578) **Full Changelog**: [https://github.com/apify/apify-client-js/compare/v2.9.4...v2.9.5](https://github.com/apify/apify-client-js/compare/v2.9.4...v2.9.5) ### [v2.9.4](https://github.com/apify/apify-client-js/releases/tag/v2.9.4) [​](#v294 "Direct link to heading") ##### What's Changed[​](#whats-changed-3 "Direct link to heading") * fix: add missing `isApifyIntegration` field to `Webhook` type by [@omikader](https://github.com/omikader) in [#523](https://github.com/apify/apify-client-js/pull/523) * feat: add notifications field to Schedule by [@m-murasovs](https://github.com/m-murasovs) in [#545](https://github.com/apify/apify-client-js/pull/545) * feat: added data property to API error object by [@gippy](https://github.com/gippy) in [#559](https://github.com/apify/apify-client-js/pull/559) **Full Changelog**: [https://github.com/apify/apify-client-js/compare/v2.9.3...v2.9.4](https://github.com/apify/apify-client-js/compare/v2.9.3...v2.9.4) ### [v2.9.3](https://github.com/apify/apify-client-js/releases/tag/v2.9.3) [​](#v293 "Direct link to heading") ##### What's Changed[​](#whats-changed-4 "Direct link to heading") * chore: remove warning when parseDateFields reaches depth limit by [@tobice](https://github.com/tobice) in [#521](https://github.com/apify/apify-client-js/pull/521) **Full Changelog**: [https://github.com/apify/apify-client-js/compare/v2.9.2...v2.9.3](https://github.com/apify/apify-client-js/compare/v2.9.2...v2.9.3) ### [v2.9.2](https://github.com/apify/apify-client-js/releases/tag/v2.9.2) [​](#v292 "Direct link to heading") ##### What's Changed[​](#whats-changed-5 "Direct link to heading") * feat: add monthlyUsage() and limits() endpoints to UserClients by [@tobice](https://github.com/tobice) in [#517](https://github.com/apify/apify-client-js/pull/517) * feat: parse monthlyUsage.dailyServiceUsages\[\].date as Date by [@tobice](https://github.com/tobice) in [#519](https://github.com/apify/apify-client-js/pull/519) **Full Changelog**: [https://github.com/apify/apify-client-js/compare/v2.9.1...v2.9.2](https://github.com/apify/apify-client-js/compare/v2.9.1...v2.9.2) ### [v2.9.1](https://github.com/apify/apify-client-js/releases/tag/v2.9.1) [​](#v291 "Direct link to heading") ##### What's Changed[​](#whats-changed-6 "Direct link to heading") * fix: ensure axios headers are instance of AxiosHeaders via interceptor by [@B4nan](https://github.com/B4nan) in [#515](https://github.com/apify/apify-client-js/pull/515) **Full Changelog**: [https://github.com/apify/apify-client-js/compare/v2.9.0...v2.9.1](https://github.com/apify/apify-client-js/compare/v2.9.0...v2.9.1) ### [v2.9.0](https://github.com/apify/apify-client-js/releases/tag/v2.9.0) [​](#v290 "Direct link to heading") ##### What's Changed[​](#whats-changed-7 "Direct link to heading") * fix: publish browser bundle by [@B4nan](https://github.com/B4nan) in [#506](https://github.com/apify/apify-client-js/pull/506) * fix: update axios to v1.6 by [@B4nan](https://github.com/B4nan) in [#505](https://github.com/apify/apify-client-js/pull/505) * feat: add `KeyValueStore.recordExists()` method by [@barjin](https://github.com/barjin) in [#510](https://github.com/apify/apify-client-js/pull/510) * feat: add `log()` method to BuildClient by [@tobice](https://github.com/tobice) in [#509](https://github.com/apify/apify-client-js/pull/509) * feat: add `runs()` and `builds()` top level endpoints by [@foxt451](https://github.com/foxt451) in [#468](https://github.com/apify/apify-client-js/pull/468) ##### New Contributors[​](#new-contributors-1 "Direct link to heading") * [@tobice](https://github.com/tobice) made their first contribution in [#509](https://github.com/apify/apify-client-js/pull/509) **Full Changelog**: [https://github.com/apify/apify-client-js/compare/v2.8.6...v2.9.0](https://github.com/apify/apify-client-js/compare/v2.8.6...v2.9.0) ### [v2.8.6](https://github.com/apify/apify-client-js/releases/tag/v2.8.6) [​](#v286 "Direct link to heading") ##### What's Changed[​](#whats-changed-8 "Direct link to heading") * fix: replace ReadableStream with Readable by [@foxt451](https://github.com/foxt451) in [#463](https://github.com/apify/apify-client-js/pull/463) * fix: add missing properties to `ActorCollectionCreateOptions` type by [@jirimoravcik](https://github.com/jirimoravcik) in [#486](https://github.com/apify/apify-client-js/pull/486) * feat(request-queue): Limit payload size for batchAddRequests() by [@drobnikj](https://github.com/drobnikj) in [#489](https://github.com/apify/apify-client-js/pull/489) * docs: add code owner for documentation by [@TC-MO](https://github.com/TC-MO) in [#488](https://github.com/apify/apify-client-js/pull/488) ##### New Contributors[​](#new-contributors-2 "Direct link to heading") * [@foxt451](https://github.com/foxt451) made their first contribution in [#463](https://github.com/apify/apify-client-js/pull/463) * [@TC-MO](https://github.com/TC-MO) made their first contribution in [#488](https://github.com/apify/apify-client-js/pull/488) **Full Changelog**: [https://github.com/apify/apify-client-js/compare/v2.8.4...v2.8.6](https://github.com/apify/apify-client-js/compare/v2.8.4...v2.8.6) ### [v2.8.4](https://github.com/apify/apify-client-js/releases/tag/v2.8.4) [​](#v284 "Direct link to heading") ##### What's Changed[​](#whats-changed-9 "Direct link to heading") * fix(schedule): expose other fields when id optional by [@omikader](https://github.com/omikader) in [#451](https://github.com/apify/apify-client-js/pull/451) ##### New Contributors[​](#new-contributors-3 "Direct link to heading") * [@omikader](https://github.com/omikader) made their first contribution in [#451](https://github.com/apify/apify-client-js/pull/451) **Full Changelog**: [https://github.com/apify/apify-client-js/compare/v2.8.2...v2.8.4](https://github.com/apify/apify-client-js/compare/v2.8.2...v2.8.4) ### [v.2.8.2](https://github.com/apify/apify-client-js/releases/tag/v2.8.2) [​](#v282 "Direct link to heading") ##### What's Changed[​](#whats-changed-10 "Direct link to heading") * ci: test on node 20 + improve tests workflow by [@B4nan](https://github.com/B4nan) in [#430](https://github.com/apify/apify-client-js/pull/430) * feat: Add how to install javascript Apify client by [@webrdaniel](https://github.com/webrdaniel) in [#440](https://github.com/apify/apify-client-js/pull/440) * fix: ScheduleUpdateData type by [@magne4000](https://github.com/magne4000) in [#276](https://github.com/apify/apify-client-js/pull/276) ##### New Contributors[​](#new-contributors-4 "Direct link to heading") * [@webrdaniel](https://github.com/webrdaniel) made their first contribution in [#440](https://github.com/apify/apify-client-js/pull/440) * [@magne4000](https://github.com/magne4000) made their first contribution in [#276](https://github.com/apify/apify-client-js/pull/276) **Full Changelog**: [https://github.com/apify/apify-client-js/compare/v2.8.1...v2.8.2](https://github.com/apify/apify-client-js/compare/v2.8.1...v2.8.2) ### [v2.8.1](https://github.com/apify/apify-client-js/releases/tag/v2.8.1) [​](#v281 "Direct link to heading") ##### What's Changed[​](#whats-changed-11 "Direct link to heading") * fix: don't parse non-date strings by [@barjin](https://github.com/barjin) in [#412](https://github.com/apify/apify-client-js/pull/412) * chore: Removed references to issuesEnabled by [@Jkuzz](https://github.com/Jkuzz) in [#416](https://github.com/apify/apify-client-js/pull/416) * feat: add new webhook fields by [@m-murasovs](https://github.com/m-murasovs) in [#426](https://github.com/apify/apify-client-js/pull/426) * feat: Add delete to runs and builds by [@Jkuzz](https://github.com/Jkuzz) in [#428](https://github.com/apify/apify-client-js/pull/428) ##### New Contributors[​](#new-contributors-5 "Direct link to heading") * [@Jkuzz](https://github.com/Jkuzz) made their first contribution in [#416](https://github.com/apify/apify-client-js/pull/416) **Full Changelog**: [https://github.com/apify/apify-client-js/compare/v2.8.0...v2.8.1](https://github.com/apify/apify-client-js/compare/v2.8.0...v2.8.1) ### [v2.8.0](https://github.com/apify/apify-client-js/releases/tag/v2.8.0) [​](#v280 "Direct link to heading") ##### What's Changed[​](#whats-changed-12 "Direct link to heading") * feat: Add Actor reboot method by [@jirimoravcik](https://github.com/jirimoravcik) in [#408](https://github.com/apify/apify-client-js/pull/408) **Full Changelog**: [https://github.com/apify/apify-client-js/compare/v2.7.2...v2.8.0](https://github.com/apify/apify-client-js/compare/v2.7.2...v2.8.0) ### [v2.7.2](https://github.com/apify/apify-client-js/releases/tag/v2.7.2) [​](#v272 "Direct link to heading") ##### What's Changed[​](#whats-changed-13 "Direct link to heading") * feat: Rename APIFY\_ACTOR\_MAX\_ITEMS to ACTOR\_MAX\_PAID\_DATASET\_ITEMS by [@novotnyj](https://github.com/novotnyj) in [#353](https://github.com/apify/apify-client-js/pull/353) * feat(runs, builds): Add usage usd into Actor run and build types by [@drobnikj](https://github.com/drobnikj) in [#355](https://github.com/apify/apify-client-js/pull/355) * feat: Add shouldInterpolateStrings field to webhook type by [@valekjo](https://github.com/valekjo) in [#358](https://github.com/apify/apify-client-js/pull/358) * feat: Use Actor/Apify env vars instead of `ENV_VARS` by [@jirimoravcik](https://github.com/jirimoravcik) in [#373](https://github.com/apify/apify-client-js/pull/373) * feat: Added StoreCollectionClient class useful for listing Actors in Apify Store by [@drobnikj](https://github.com/drobnikj) in [#395](https://github.com/apify/apify-client-js/pull/395) * docs: Change subtitle by [@barjin](https://github.com/barjin) in [#380](https://github.com/apify/apify-client-js/pull/380) * fix(docs): Fix docs for resource clients to hide constructor by [@drobnikj](https://github.com/drobnikj) in [#397](https://github.com/apify/apify-client-js/pull/397) * fix: Update index.js by [@jancurn](https://github.com/jancurn) in [#379](https://github.com/apify/apify-client-js/pull/379) * chore: Use new workflow secrets by [@fnesveda](https://github.com/fnesveda) in [#354](https://github.com/apify/apify-client-js/pull/354) * chore: Invalidate CloudFront cache after docs deploy by [@fnesveda](https://github.com/fnesveda) in [#357](https://github.com/apify/apify-client-js/pull/357) * chore: Update dependencies **Full Changelog**: [https://github.com/apify/apify-client-js/compare/v2.7.1...v2.7.2](https://github.com/apify/apify-client-js/compare/v2.7.1...v2.7.2) ### [v2.7.1](https://github.com/apify/apify-client-js/releases/tag/v2.7.1) [​](#v271 "Direct link to heading") ##### What's Changed[​](#whats-changed-14 "Direct link to heading") * fix: add `types` to package `exports` by [@B4nan](https://github.com/B4nan) in [#349](https://github.com/apify/apify-client-js/pull/349) **Full Changelog**: [https://github.com/apify/apify-client-js/compare/v2.7.0...v2.7.1](https://github.com/apify/apify-client-js/compare/v2.7.0...v2.7.1) ### [v2.7.0](https://github.com/apify/apify-client-js/releases/tag/v2.7.0) [​](#v270 "Direct link to heading") ##### What's Changed[​](#whats-changed-15 "Direct link to heading") * fix: `isAtHome` value in User-Agent header by [@mvolfik](https://github.com/mvolfik) in [#286](https://github.com/apify/apify-client-js/pull/286) * fix: types for actor run by [@drobnikj](https://github.com/drobnikj) in [#331](https://github.com/apify/apify-client-js/pull/331) * fix: improve reading of the version when using bundlers by [@vladfrangu](https://github.com/vladfrangu) in [#332](https://github.com/apify/apify-client-js/pull/332) * feat: add support for `maxItems` in run options by [@novotnyj](https://github.com/novotnyj) in [#330](https://github.com/apify/apify-client-js/pull/330) * feat: mark Request Queue v2 methods as stable by [@drobnikj](https://github.com/drobnikj) in [#334](https://github.com/apify/apify-client-js/pull/334) * feat: add standard handing for setStatusMessage by [@barjin](https://github.com/barjin) in [#333](https://github.com/apify/apify-client-js/pull/333) ##### New Contributors[​](#new-contributors-6 "Direct link to heading") * [@novotnyj](https://github.com/novotnyj) made their first contribution in [#330](https://github.com/apify/apify-client-js/pull/330) **Full Changelog**: [https://github.com/apify/apify-client-js/compare/v2.6.3...v2.7.0](https://github.com/apify/apify-client-js/compare/v2.6.3...v2.7.0) ### [v2.6.3](https://github.com/apify/apify-client-js/releases/tag/v2.6.3) [​](#v263 "Direct link to heading") ##### What's Changed[​](#whats-changed-16 "Direct link to heading") * feat: isStatusMessageTerminal in RunUpdate interface by [@barjin](https://github.com/barjin) in [#306](https://github.com/apify/apify-client-js/pull/306) **Full Changelog**: [https://github.com/apify/apify-client-js/compare/v2.6.2...v2.6.3](https://github.com/apify/apify-client-js/compare/v2.6.2...v2.6.3) ### [v2.6.2](https://github.com/apify/apify-client-js/releases/tag/v2.6.2) [​](#v262 "Direct link to heading") ##### What's Changed[​](#whats-changed-17 "Direct link to heading") * fix: `Actor.call` and `Task.call` accept `waitSecs` not `waitForFinish` by [@vladfrangu](https://github.com/vladfrangu) in [#283](https://github.com/apify/apify-client-js/pull/283) * feat: re-export useful types and classes by [@vladfrangu](https://github.com/vladfrangu) in [#285](https://github.com/apify/apify-client-js/pull/285) * fix(types): correct extends clause for Dataset entries by [@vladfrangu](https://github.com/vladfrangu) in [#284](https://github.com/apify/apify-client-js/pull/284) * fix: Correct docs links for actor env vars, some refactoring by [@jirimoravcik](https://github.com/jirimoravcik) in [#287](https://github.com/apify/apify-client-js/pull/287) * fix: make ActorUpdateOptions type have optional fields by [@metalwarrior665](https://github.com/metalwarrior665) in [#288](https://github.com/apify/apify-client-js/pull/288) * fix: correctly set default client headers by [@valekjo](https://github.com/valekjo) in [#290](https://github.com/apify/apify-client-js/pull/290) **Full Changelog**: [https://github.com/apify/apify-client-js/compare/v2.6.1...v2.6.2](https://github.com/apify/apify-client-js/compare/v2.6.1...v2.6.2) ### [v2.6.1](https://github.com/apify/apify-client-js/releases/tag/v2.6.1) [​](#v261 "Direct link to heading") ##### What's Changed[​](#whats-changed-18 "Direct link to heading") * feat: drop single file support by [@valekjo](https://github.com/valekjo) in [#257](https://github.com/apify/apify-client-js/pull/257) * feat: update actor types by [@HonzaTuron](https://github.com/HonzaTuron) in [#263](https://github.com/apify/apify-client-js/pull/263) * feat: Add flatten param to Dataset items listing by [@Strajk](https://github.com/Strajk) in [#264](https://github.com/apify/apify-client-js/pull/264) * feat: Add optional title field to task, schedule, key-value store, dataset, and request queue by [@valekjo](https://github.com/valekjo) in [#271](https://github.com/apify/apify-client-js/pull/271) * fix: Add `defaultRequestQueueId` property to `ActorRun` type by [@fnesveda](https://github.com/fnesveda) in [#268](https://github.com/apify/apify-client-js/pull/268) **Full Changelog**: [https://github.com/apify/apify-client-js/compare/v2.6.0...v2.6.1](https://github.com/apify/apify-client-js/compare/v2.6.0...v2.6.1) ### [v2.6.0](https://github.com/apify/apify-client-js/releases/tag/v2.6.0) [​](#v260 "Direct link to heading") ##### What's Changed[​](#whats-changed-19 "Direct link to heading") * Add run.update() method for setting fields on runs. You can update statusMessage of run using this method. by [@barjin](https://github.com/barjin) in [#258](https://github.com/apify/apify-client-js/pull/258) * Fix parsing ApifyError for method called with forceBuffer param to true. by [@drobnikj](https://github.com/drobnikj) in [#260](https://github.com/apify/apify-client-js/pull/260) * Fix stream support, related with [https://github.com/axios/axios/issues/1045](https://github.com/axios/axios/issues/1045) by [@mvolfik](https://github.com/mvolfik) in [#256](https://github.com/apify/apify-client-js/pull/256) ##### New Contributors[​](#new-contributors-7 "Direct link to heading") * [@barjin](https://github.com/barjin) made their first contribution in [#258](https://github.com/apify/apify-client-js/pull/258) * [@mvolfik](https://github.com/mvolfik) made their first contribution in [#256](https://github.com/apify/apify-client-js/pull/256) **Full Changelog**: [https://github.com/apify/apify-client-js/compare/v2.5.2...v2.6.0](https://github.com/apify/apify-client-js/compare/v2.5.2...v2.6.0) ### [v2.5.2](https://github.com/apify/apify-client-js/releases/tag/v2.5.2) [​](#v252 "Direct link to heading") ##### What's Changed[​](#whats-changed-20 "Direct link to heading") * Adjust default parallels and retries for batch add requests by [@drobnikj](https://github.com/drobnikj) in [#255](https://github.com/apify/apify-client-js/pull/255) **Full Changelog**: [https://github.com/apify/apify-client-js/compare/v2.5.1...v2.5.2](https://github.com/apify/apify-client-js/compare/v2.5.1...v2.5.2) ### [v2.5.1](https://github.com/apify/apify-client-js/releases/tag/v2.5.1) [​](#v251 "Direct link to heading") ##### What's Changed[​](#whats-changed-21 "Direct link to heading") * Fix ActorRun - correct type for `status` by [@vladfrangu](https://github.com/vladfrangu) in [#254](https://github.com/apify/apify-client-js/pull/254) * Add methods to list all requests in queue, `requestQueueClient.listRequests()` and `requestQueueClient.paginateRequests()`. The paginate requests return an async iterator. by [@drobnikj](https://github.com/drobnikj) in [#249](https://github.com/apify/apify-client-js/pull/249) for await (const page of rqClient.paginateRequests()) { // Do something with page.items} **Full Changelog**: [https://github.com/apify/apify-client-js/compare/v2.5.0...v2.5.1](https://github.com/apify/apify-client-js/compare/v2.5.0...v2.5.1) ### [v2.5.0](https://github.com/apify/apify-client-js/releases/tag/v2.5.0) [​](#v250 "Direct link to heading") ##### What's Changed[​](#whats-changed-22 "Direct link to heading") * feat: origin param added for last actor/task run endpoints by [@HonzaKirchner](https://github.com/HonzaKirchner) in [#248](https://github.com/apify/apify-client-js/pull/248) * chore: version update by [@HonzaKirchner](https://github.com/HonzaKirchner) in [#250](https://github.com/apify/apify-client-js/pull/250) ##### New Contributors[​](#new-contributors-8 "Direct link to heading") * [@HonzaKirchner](https://github.com/HonzaKirchner) made their first contribution in [#248](https://github.com/apify/apify-client-js/pull/248) **Full Changelog**: [https://github.com/apify/apify-client-js/compare/v2.4.1...v2.5.0](https://github.com/apify/apify-client-js/compare/v2.4.1...v2.5.0) ### [v2.4.1](https://github.com/apify/apify-client-js/releases/tag/v2.4.1) [​](#v241 "Direct link to heading") ##### What's Changed[​](#whats-changed-23 "Direct link to heading") * feat: Add request queue methods `listAndLockHead`, `prolongRequestLock`, `deleteRequestLock` by [@drobnikj](https://github.com/drobnikj) in [#246](https://github.com/apify/apify-client-js/pull/246) **Full Changelog**: [https://github.com/apify/apify-client-js/compare/v2.4.0...v2.4.1](https://github.com/apify/apify-client-js/compare/v2.4.0...v2.4.1) ### [v2.4.0](https://github.com/apify/apify-client-js/releases/tag/v2.4.0) [​](#v240 "Direct link to heading") ##### What's Changed[​](#whats-changed-24 "Direct link to heading") * fix: Add exponential backoff to batchAddRequests, untie batch and client settings by [@jirimoravcik](https://github.com/jirimoravcik) in [#243](https://github.com/apify/apify-client-js/pull/243) **Full Changelog**: [https://github.com/apify/apify-client-js/compare/v2.3.1...v2.4.0](https://github.com/apify/apify-client-js/compare/v2.3.1...v2.4.0) ### [v2.3.1](https://github.com/apify/apify-client-js/releases/tag/v2.3.1) [​](#v231 "Direct link to heading") ##### What's Changed[​](#whats-changed-25 "Direct link to heading") * Fix: Retries in batch requests insert endpoint [@drobnikj](https://github.com/drobnikj) in [#242](https://github.com/apify/apify-client-js/pull/242) **Full Changelog**: [https://github.com/apify/apify-client-js/compare/v2.3.0...v2.3.1](https://github.com/apify/apify-client-js/compare/v2.3.0...v2.3.1) * [2.11.2](#2112) * [2.11.1](#2111) * [2.11.0](#2110) * [2.10.0](#2100) * [v2.9.7](#v297) * [v2.9.6](#v296) * [v2.9.5](#v295) * [v2.9.4](#v294) * [v2.9.3](#v293) * [v2.9.2](#v292) * [v2.9.1](#v291) * [v2.9.0](#v290) * [v2.8.6](#v286) * [v2.8.4](#v284) * [v.2.8.2](#v282) * [v2.8.1](#v281) * [v2.8.0](#v280) * [v2.7.2](#v272) * [v2.7.1](#v271) * [v2.7.0](#v270) * [v2.6.3](#v263) * [v2.6.2](#v262) * [v2.6.1](#v261) * [v2.6.0](#v260) * [v2.5.2](#v252) * [v2.5.1](#v251) * [v2.5.0](#v250) * [v2.4.1](#v241) * [v2.4.0](#v240) * [v2.3.1](#v231) --- # Abort run | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Abort run ========= POST /v2/acts/:actorId/runs/:runId/abort ----------------------------------- deprecated This endpoint has been deprecated and may be replaced or removed in future versions of the API. **\[DEPRECATED\]** API endpoints related to run of the Actor were moved under new namespace [`actor-runs`](#/reference/actor-runs) . Aborts an Actor run and returns an object that contains all the details about the run. Only runs that are starting or running are aborted. For runs with status `FINISHED`, `FAILED`, `ABORTING` and `TIMED-OUT` this call does nothing. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 **Response Headers** --- # Get run | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Get run ======= GET /v2/acts/:actorId/runs/:runId ----------------------------- deprecated This endpoint has been deprecated and may be replaced or removed in future versions of the API. **\[DEPRECATED\]** API endpoints related to run of the Actor were moved under new namespace [`actor-runs`](#/reference/actor-runs) . Gets an object that contains all the details about a specific run of an Actor. By passing the optional `waitForFinish` parameter the API endpoint will synchronously wait for the run to finish. This is useful to avoid periodic polling when waiting for Actor run to complete. This endpoint does not require the authentication token. Instead, calls are authenticated using a hard-to-guess ID of the run. However, if you access the endpoint without the token, certain attributes, such as `usageUsd` and `usageTotalUsd`, will be hidden. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 **Response Headers** --- # Getting started | API client for JavaScript | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) This is unreleased documentation for API client for JavaScript | Apify Documentation **Next** version. For up-to-date documentation, see the **[latest version](/api/client/js/docs) ** (2.11). Version: Next On this page `apify-client` is the official library to access the [Apify REST API](https://docs.apify.com/api/v2) from your JavaScript/TypeScript applications. It runs both in Node.js and browser and provides useful features like automatic retries and convenience functions that improve the experience of using the Apify API. All requests and responses (including errors) are encoded in JSON format with UTF-8 encoding. Pre-requisites[​](#pre-requisites "Direct link to heading") ------------------------------------------------------------ `apify-client` requires Node.js version 16 or higher. Node.js is available for download on the [official website](https://nodejs.org/) . Check for your current node version by running: node -v Installation[​](#installation "Direct link to heading") -------------------------------------------------------- You can install the client via [NPM](https://www.npmjs.com/) or use any other package manager of your choice. * NPM * Yarn * PNPM * Bun npm i apify-client yarn add apify-client pnpm add apify-client bun add apify-client Authentication and Initialization[​](#authentication-and-initialization "Direct link to heading") -------------------------------------------------------------------------------------------------- To use the client, you need an [API token](https://docs.apify.com/platform/integrations/api#api-token) . You can find your token under [Integrations](https://console.apify.com/account/integrations) tab in Apify Console. Copy the token and initialize the client by providing the token (`MY-APIFY-TOKEN`) as a parameter to the `ApifyClient` constructor. // import Apify clientimport { ApifyClient } from 'apify-client';// Client initialization with the API tokenconst client = new ApifyClient({ token: 'MY-APIFY-TOKEN',}); Secure access The API token is used to authorize your requests to the Apify API. You can be charged for the usage of the underlying services, so do not share your API token with untrusted parties or expose it on the client side of your applications Quick start[​](#quick-start "Direct link to heading") ------------------------------------------------------ One of the most common use cases is starting [Actors](https://docs.apify.com/platform/actors) (serverless programs running in the [Apify cloud](https://docs.apify.com/platform) ) and getting results from their [datasets](https://docs.apify.com/platform/storage/dataset) (storage) after they finish the job (usually scraping, automation processes or data processing). import { ApifyClient } from 'apify-client';const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });// Starts an Actor and waits for it to finishconst { defaultDatasetId } = await client.actor('username/actor-name').call();// Lists items from the Actor's datasetconst { items } = await client.dataset(defaultDatasetId).listItems(); ### Running Actors[​](#running-actors "Direct link to heading") To start an Actor, you can use the [ActorClient](/api/client/js/reference/class/ActorClient) (`client.actor()`) and pass the Actor's ID (e.g. `john-doe/my-cool-actor`) to define which Actor you want to run. The Actor's ID is a combination of the username and the Actor owner’s username. You can run both your own Actors and [Actors from Apify Store](https://docs.apify.com/platform/actors/running/actors-in-store) . #### Passing input to the Actor[​](#passing-input-to-the-actor "Direct link to heading") To define the Actor's input, you can pass an object to the [`call()`](/api/client/js/reference/class/ActorClient#call) method. The input object can be any JSON object that the Actor expects (respects the Actor's [input schema](https://docs.apify.com/platform/actors/development/actor-definition/input-schema) ). The input object is used to pass configuration to the Actor, such as URLs to scrape, search terms, or any other data. import { ApifyClient } from 'apify-client';const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });// Runs an Actor with an input and waits for it to finish.const { defaultDatasetId } = await client.actor('username/actor-name').call({ some: 'input',}); ### Getting results from the dataset[​](#getting-results-from-the-dataset "Direct link to heading") To get the results from the dataset, you can use the [DatasetClient](/api/client/js/reference/class/DatasetClient) (`client.dataset()`) and [`listItems()`](/api/client/js/reference/class/DatasetClient#listItems) method. You need to pass the dataset ID to define which dataset you want to access. You can get the dataset ID from the Actor's run object (represented by `defaultDatasetId`). import { ApifyClient } from 'apify-client';const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });// Lists items from the Actor's dataset.const { items } = await client.dataset('dataset-id').listItems(); Dataset access Running an Actor might take time, depending on the Actor's complexity and the amount of data it processes. If you want only to get data and have an immediate response you should access the existing dataset of the finished [Actor run](https://docs.apify.com/platform/actors/running/runs-and-builds#runs) . Usage concepts[​](#usage-concepts "Direct link to heading") ------------------------------------------------------------ The `ApifyClient` interface follows a generic pattern that applies to all of its components. By calling individual methods of `ApifyClient`, specific clients that target individual API resources are created. There are two types of those clients: * [`actorClient`](/api/client/js/reference/class/ActorClient) : a client for the management of a single resource * [`actorCollectionClient`](/api/client/js/reference/class/ActorCollectionClient) : a client for the collection of resources import { ApifyClient } from 'apify-client';const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });// Collection clients do not require a parameter.const actorCollectionClient = client.actors();// Creates an actor with the name: my-actor.const myActor = await actorCollectionClient.create({ name: 'my-actor-name' });// List all your used Actors (both own and from Apify Store)const { items } = await actorCollectionClient.list(); Resource identification The resource ID can be either the `id` of the said resource, or a combination of your `username/resource-name`. import { ApifyClient } from 'apify-client';const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });// Resource clients accept an ID of the resource.const actorClient = client.actor('username/actor-name');// Fetches the john-doe/my-actor object from the API.const myActor = await actorClient.get();// Starts the run of john-doe/my-actor and returns the Run object.const myActorRun = await actorClient.start(); ### Nested clients[​](#nested-clients "Direct link to heading") Sometimes clients return other clients. That's to simplify working with nested collections, such as runs of a given Actor. import { ApifyClient } from 'apify-client';const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });const actorClient = client.actor('username/actor-name');const runsClient = actorClient.runs();// Lists the last 10 runs of your Actor.const { items } = await runsClient.list({ limit: 10, desc: true});// Select the last run of your Actor that finished// with a SUCCEEDED status.const lastSucceededRunClient = actorClient.lastRun({ status: 'SUCCEEDED' });// Fetches items from the run's dataset.const { items } = await lastSucceededRunClient.dataset() .listItems(); The quick access to `dataset` and other storage directly from the run client can be used with the [`lastRun()`](/api/client/js/reference/class/ActorClient#lastRun)  method. Features[​](#features "Direct link to heading") ------------------------------------------------ Based on the endpoint, the client automatically extracts the relevant data and returns it in the expected format. Date strings are automatically converted to `Date` objects. For exceptions, the client throws an [`ApifyApiError`](/api/client/js/reference/class/ApifyApiError) , which wraps the plain JSON errors returned by API and enriches them with other contexts for easier debugging. import { ApifyClient } from 'apify-client';const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });try { const { items } = await client.dataset("non-existing-dataset-id").listItems();} catch (error) { // The error is an instance of ApifyApiError const { message, type, statusCode, clientMethod, path } = error; // Log error for easier debugging console.log({ message, statusCode, clientMethod, type });} ### Retries with exponential backoff[​](#retries-with-exponential-backoff "Direct link to heading") Network communication sometimes fails. That's a given. The client will automatically retry requests that failed due to a network error, an internal error of the Apify API (HTTP 500+), or a rate limit error (HTTP 429). By default, it will retry up to 8 times. The first retry will be attempted after ~500ms, the second after ~1000ms, and so on. You can configure those parameters using the `maxRetries` and `minDelayBetweenRetriesMillis` options of the `ApifyClient` constructor. import { ApifyClient } from 'apify-client';const client = new ApifyClient({ token: 'MY-APIFY-TOKEN', maxRetries: 8, minDelayBetweenRetriesMillis: 500, // 0.5s timeoutSecs: 360 // 6 mins}); ### Convenience functions and options[​](#convenience-functions-and-options "Direct link to heading") Some actions can't be performed by the API itself, such as indefinite waiting for an Actor run to finish (because of network timeouts). The client provides convenient `call()` and `waitForFinish()` functions that do that. If the limit is reached, the returned promise is resolved to a run object that will have status `READY` or `RUNNING` and it will not contain the Actor run output. [Key-value store](https://docs.apify.com/platform/storage/key-value-store) records can be retrieved as objects, buffers, or streams via the respective options, dataset items can be fetched as individual objects or serialized data. import { ApifyClient } from 'apify-client';const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });// Starts an Actor and waits for it to finish.const finishedActorRun = await client.actor('username/actor-name').call();// Starts an Actor and waits maximum 60s for the finish const { status } = await client.actor('username/actor-name').start({ waitForFinish: 60, // 1 minute}); ### Pagination[​](#pagination "Direct link to heading") Most methods named `list` or `listSomething` return a [`Promise`](/api/client/js/reference/interface/PaginatedList) . There are some exceptions though, like `listKeys` or `listHead` which paginate differently. The results you're looking for are always stored under `items` and you can use the `limit` property to get only a subset of results. Other props are also available, depending on the method. import { ApifyClient } from 'apify-client';const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });// Resource clients accept an ID of the resource.const datasetClient = client.dataset('dataset-id');// Number of items per pageconst limit = 1000;// Initial offsetlet offset = 0; // Array to store all itemslet allItems = []; while (true) { const { items, total } = await datasetClient.listItems({ limit, offset }); console.log(`Fetched ${items.length} items`); // Merge new items with other already loaded items allItems.push(...items); // If there are no more items to fetch, exit the loading if (offset + limit >= total) { break; } offset += limit;}console.log(`Overall fetched ${allItems.length} items`); * [Pre-requisites](#pre-requisites) * [Installation](#installation) * [Authentication and Initialization](#authentication-and-initialization) * [Quick start](#quick-start) * [Running Actors](#running-actors) * [Getting results from the dataset](#getting-results-from-the-dataset) * [Usage concepts](#usage-concepts) * [Nested clients](#nested-clients) * [Features](#features) * [Retries with exponential backoff](#retries-with-exponential-backoff) * [Convenience functions and options](#convenience-functions-and-options) * [Pagination](#pagination) --- # apify-client | API | API client for JavaScript | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Version: 2.11 On this page Index[](#Index) ---------------- ### Enumerations * [DownloadItemsFormat](/api/client/js/reference/enum/DownloadItemsFormat) * [PlatformFeature](/api/client/js/reference/enum/PlatformFeature) * [ScheduleActions](/api/client/js/reference/enum/ScheduleActions) * [WebhookDispatchStatus](/api/client/js/reference/enum/WebhookDispatchStatus) ### Classes * [ActorClient](/api/client/js/reference/class/ActorClient) * [ActorCollectionClient](/api/client/js/reference/class/ActorCollectionClient) * [ApifyApiError](/api/client/js/reference/class/ApifyApiError) * [ApifyClient](/api/client/js/reference/class/ApifyClient) * [BuildClient](/api/client/js/reference/class/BuildClient) * [BuildCollectionClient](/api/client/js/reference/class/BuildCollectionClient) * [DatasetClient](/api/client/js/reference/class/DatasetClient) * [DatasetCollectionClient](/api/client/js/reference/class/DatasetCollectionClient) * [InvalidResponseBodyError](/api/client/js/reference/class/InvalidResponseBodyError) * [KeyValueStoreClient](/api/client/js/reference/class/KeyValueStoreClient) * [KeyValueStoreCollectionClient](/api/client/js/reference/class/KeyValueStoreCollectionClient) * [LogClient](/api/client/js/reference/class/LogClient) * [RequestQueueClient](/api/client/js/reference/class/RequestQueueClient) * [RequestQueueCollectionClient](/api/client/js/reference/class/RequestQueueCollectionClient) * [RunClient](/api/client/js/reference/class/RunClient) * [RunCollectionClient](/api/client/js/reference/class/RunCollectionClient) * [ScheduleClient](/api/client/js/reference/class/ScheduleClient) * [ScheduleCollectionClient](/api/client/js/reference/class/ScheduleCollectionClient) * [StoreCollectionClient](/api/client/js/reference/class/StoreCollectionClient) * [TaskClient](/api/client/js/reference/class/TaskClient) * [TaskCollectionClient](/api/client/js/reference/class/TaskCollectionClient) * [UserClient](/api/client/js/reference/class/UserClient) * [WebhookClient](/api/client/js/reference/class/WebhookClient) * [WebhookCollectionClient](/api/client/js/reference/class/WebhookCollectionClient) * [WebhookDispatchClient](/api/client/js/reference/class/WebhookDispatchClient) * [WebhookDispatchCollectionClient](/api/client/js/reference/class/WebhookDispatchCollectionClient) ### Interfaces * [AccountAndUsageLimits](/api/client/js/reference/interface/AccountAndUsageLimits) * [Actor](/api/client/js/reference/interface/Actor) * [ActorBuildOptions](/api/client/js/reference/interface/ActorBuildOptions) * [ActorCallOptions](/api/client/js/reference/interface/ActorCallOptions) * [ActorChargeEvent](/api/client/js/reference/interface/ActorChargeEvent) * [ActorCollectionCreateOptions](/api/client/js/reference/interface/ActorCollectionCreateOptions) * [ActorCollectionListItem](/api/client/js/reference/interface/ActorCollectionListItem) * [ActorCollectionListOptions](/api/client/js/reference/interface/ActorCollectionListOptions) * [ActorDefaultRunOptions](/api/client/js/reference/interface/ActorDefaultRunOptions) * [ActorDefinition](/api/client/js/reference/interface/ActorDefinition) * [ActorExampleRunInput](/api/client/js/reference/interface/ActorExampleRunInput) * [ActorLastRunOptions](/api/client/js/reference/interface/ActorLastRunOptions) * [ActorRun](/api/client/js/reference/interface/ActorRun) * [ActorRunListItem](/api/client/js/reference/interface/ActorRunListItem) * [ActorRunMeta](/api/client/js/reference/interface/ActorRunMeta) * [ActorRunOptions](/api/client/js/reference/interface/ActorRunOptions) * [ActorRunStats](/api/client/js/reference/interface/ActorRunStats) * [ActorRunUsage](/api/client/js/reference/interface/ActorRunUsage) * [ActorStandby](/api/client/js/reference/interface/ActorStandby) * [ActorStartOptions](/api/client/js/reference/interface/ActorStartOptions) * [ActorStats](/api/client/js/reference/interface/ActorStats) * [ActorStoreList](/api/client/js/reference/interface/ActorStoreList) * [ActorTaggedBuild](/api/client/js/reference/interface/ActorTaggedBuild) * [ApifyClientOptions](/api/client/js/reference/interface/ApifyClientOptions) * [Build](/api/client/js/reference/interface/Build) * [BuildClientGetOptions](/api/client/js/reference/interface/BuildClientGetOptions) * [BuildClientWaitForFinishOptions](/api/client/js/reference/interface/BuildClientWaitForFinishOptions) * [BuildCollectionClientListOptions](/api/client/js/reference/interface/BuildCollectionClientListOptions) * [BuildMeta](/api/client/js/reference/interface/BuildMeta) * [BuildOptions](/api/client/js/reference/interface/BuildOptions) * [BuildStats](/api/client/js/reference/interface/BuildStats) * [BuildUsage](/api/client/js/reference/interface/BuildUsage) * [Current](/api/client/js/reference/interface/Current) * [Dataset](/api/client/js/reference/interface/Dataset) * [DatasetClientDownloadItemsOptions](/api/client/js/reference/interface/DatasetClientDownloadItemsOptions) * [DatasetClientListItemOptions](/api/client/js/reference/interface/DatasetClientListItemOptions) * [DatasetClientUpdateOptions](/api/client/js/reference/interface/DatasetClientUpdateOptions) * [DatasetCollectionClientGetOrCreateOptions](/api/client/js/reference/interface/DatasetCollectionClientGetOrCreateOptions) * [DatasetCollectionClientListOptions](/api/client/js/reference/interface/DatasetCollectionClientListOptions) * [DatasetStatistics](/api/client/js/reference/interface/DatasetStatistics) * [DatasetStats](/api/client/js/reference/interface/DatasetStats) * [FieldStatistics](/api/client/js/reference/interface/FieldStatistics) * [FlatPricePerMonthActorPricingInfo](/api/client/js/reference/interface/FlatPricePerMonthActorPricingInfo) * [FreeActorPricingInfo](/api/client/js/reference/interface/FreeActorPricingInfo) * [KeyValueClientGetRecordOptions](/api/client/js/reference/interface/KeyValueClientGetRecordOptions) * [KeyValueClientListKeysOptions](/api/client/js/reference/interface/KeyValueClientListKeysOptions) * [KeyValueClientListKeysResult](/api/client/js/reference/interface/KeyValueClientListKeysResult) * [KeyValueClientUpdateOptions](/api/client/js/reference/interface/KeyValueClientUpdateOptions) * [KeyValueListItem](/api/client/js/reference/interface/KeyValueListItem) * [KeyValueStore](/api/client/js/reference/interface/KeyValueStore) * [KeyValueStoreCollectionClientGetOrCreateOptions](/api/client/js/reference/interface/KeyValueStoreCollectionClientGetOrCreateOptions) * [KeyValueStoreCollectionClientListOptions](/api/client/js/reference/interface/KeyValueStoreCollectionClientListOptions) * [KeyValueStoreRecord](/api/client/js/reference/interface/KeyValueStoreRecord) * [KeyValueStoreStats](/api/client/js/reference/interface/KeyValueStoreStats) * [Limits](/api/client/js/reference/interface/Limits) * [MonthlyUsage](/api/client/js/reference/interface/MonthlyUsage) * [MonthlyUsageCycle](/api/client/js/reference/interface/MonthlyUsageCycle) * [OpenApiDefinition](/api/client/js/reference/interface/OpenApiDefinition) * [PaginatedList](/api/client/js/reference/interface/PaginatedList) * [PricePerDatasetItemActorPricingInfo](/api/client/js/reference/interface/PricePerDatasetItemActorPricingInfo) * [PricePerEventActorPricingInfo](/api/client/js/reference/interface/PricePerEventActorPricingInfo) * [PricingInfo](/api/client/js/reference/interface/PricingInfo) * [ProxyGroup](/api/client/js/reference/interface/ProxyGroup) * [RequestQueue](/api/client/js/reference/interface/RequestQueue) * [RequestQueueClientAddRequestOptions](/api/client/js/reference/interface/RequestQueueClientAddRequestOptions) * [RequestQueueClientAddRequestResult](/api/client/js/reference/interface/RequestQueueClientAddRequestResult) * [RequestQueueClientBatchAddRequestWithRetriesOptions](/api/client/js/reference/interface/RequestQueueClientBatchAddRequestWithRetriesOptions) * [RequestQueueClientBatchRequestsOperationResult](/api/client/js/reference/interface/RequestQueueClientBatchRequestsOperationResult) * [RequestQueueClientDeleteRequestLockOptions](/api/client/js/reference/interface/RequestQueueClientDeleteRequestLockOptions) * [RequestQueueClientListAndLockHeadOptions](/api/client/js/reference/interface/RequestQueueClientListAndLockHeadOptions) * [RequestQueueClientListAndLockHeadResult](/api/client/js/reference/interface/RequestQueueClientListAndLockHeadResult) * [RequestQueueClientListHeadOptions](/api/client/js/reference/interface/RequestQueueClientListHeadOptions) * [RequestQueueClientListHeadResult](/api/client/js/reference/interface/RequestQueueClientListHeadResult) * [RequestQueueClientListItem](/api/client/js/reference/interface/RequestQueueClientListItem) * [RequestQueueClientListRequestsOptions](/api/client/js/reference/interface/RequestQueueClientListRequestsOptions) * [RequestQueueClientListRequestsResult](/api/client/js/reference/interface/RequestQueueClientListRequestsResult) * [RequestQueueClientPaginateRequestsOptions](/api/client/js/reference/interface/RequestQueueClientPaginateRequestsOptions) * [RequestQueueClientProlongRequestLockOptions](/api/client/js/reference/interface/RequestQueueClientProlongRequestLockOptions) * [RequestQueueClientProlongRequestLockResult](/api/client/js/reference/interface/RequestQueueClientProlongRequestLockResult) * [RequestQueueClientRequestSchema](/api/client/js/reference/interface/RequestQueueClientRequestSchema) * [RequestQueueClientUpdateOptions](/api/client/js/reference/interface/RequestQueueClientUpdateOptions) * [RequestQueueCollectionListOptions](/api/client/js/reference/interface/RequestQueueCollectionListOptions) * [RequestQueueStats](/api/client/js/reference/interface/RequestQueueStats) * [RequestQueueUserOptions](/api/client/js/reference/interface/RequestQueueUserOptions) * [RunAbortOptions](/api/client/js/reference/interface/RunAbortOptions) * [RunCollectionListOptions](/api/client/js/reference/interface/RunCollectionListOptions) * [RunGetOptions](/api/client/js/reference/interface/RunGetOptions) * [RunMetamorphOptions](/api/client/js/reference/interface/RunMetamorphOptions) * [RunResurrectOptions](/api/client/js/reference/interface/RunResurrectOptions) * [RunUpdateOptions](/api/client/js/reference/interface/RunUpdateOptions) * [RunWaitForFinishOptions](/api/client/js/reference/interface/RunWaitForFinishOptions) * [Schedule](/api/client/js/reference/interface/Schedule) * [ScheduleActionRunActor](/api/client/js/reference/interface/ScheduleActionRunActor) * [ScheduleActionRunActorTask](/api/client/js/reference/interface/ScheduleActionRunActorTask) * [ScheduleCollectionListOptions](/api/client/js/reference/interface/ScheduleCollectionListOptions) * [ScheduledActorRunInput](/api/client/js/reference/interface/ScheduledActorRunInput) * [ScheduledActorRunOptions](/api/client/js/reference/interface/ScheduledActorRunOptions) * [StoreCollectionListOptions](/api/client/js/reference/interface/StoreCollectionListOptions) * [Task](/api/client/js/reference/interface/Task) * [TaskCallOptions](/api/client/js/reference/interface/TaskCallOptions) * [TaskCollectionListOptions](/api/client/js/reference/interface/TaskCollectionListOptions) * [TaskCreateData](/api/client/js/reference/interface/TaskCreateData) * [TaskLastRunOptions](/api/client/js/reference/interface/TaskLastRunOptions) * [TaskOptions](/api/client/js/reference/interface/TaskOptions) * [TaskStats](/api/client/js/reference/interface/TaskStats) * [UsageCycle](/api/client/js/reference/interface/UsageCycle) * [User](/api/client/js/reference/interface/User) * [UserPlan](/api/client/js/reference/interface/UserPlan) * [UserProxy](/api/client/js/reference/interface/UserProxy) * [Webhook](/api/client/js/reference/interface/Webhook) * [WebhookAnyRunOfActorCondition](/api/client/js/reference/interface/WebhookAnyRunOfActorCondition) * [WebhookAnyRunOfActorTaskCondition](/api/client/js/reference/interface/WebhookAnyRunOfActorTaskCondition) * [WebhookCertainRunCondition](/api/client/js/reference/interface/WebhookCertainRunCondition) * [WebhookCollectionListOptions](/api/client/js/reference/interface/WebhookCollectionListOptions) * [WebhookDispatch](/api/client/js/reference/interface/WebhookDispatch) * [WebhookDispatchCall](/api/client/js/reference/interface/WebhookDispatchCall) * [WebhookDispatchCollectionListOptions](/api/client/js/reference/interface/WebhookDispatchCollectionListOptions) * [WebhookIdempotencyKey](/api/client/js/reference/interface/WebhookIdempotencyKey) * [WebhookStats](/api/client/js/reference/interface/WebhookStats) ### Type Aliases * [ActorChargeEvents](/api/client/js/reference#ActorChargeEvents) * [ActorCollectionListResult](/api/client/js/reference#ActorCollectionListResult) * [ActorRunPricingInfo](/api/client/js/reference#ActorRunPricingInfo) * [ActorTaggedBuilds](/api/client/js/reference#ActorTaggedBuilds) * [ActorUpdateOptions](/api/client/js/reference#ActorUpdateOptions) * [AllowedHttpMethods](/api/client/js/reference#AllowedHttpMethods) * [BuildCollectionClientListItem](/api/client/js/reference#BuildCollectionClientListItem) * [BuildCollectionClientListResult](/api/client/js/reference#BuildCollectionClientListResult) * [DatasetCollectionClientListResult](/api/client/js/reference#DatasetCollectionClientListResult) * [Dictionary](/api/client/js/reference#Dictionary) * [KeyValueStoreCollectionListResult](/api/client/js/reference#KeyValueStoreCollectionListResult) * [LimitsUpdateOptions](/api/client/js/reference#LimitsUpdateOptions) * [RequestQueueClientGetRequestResult](/api/client/js/reference#RequestQueueClientGetRequestResult) * [RequestQueueClientRequestToDelete](/api/client/js/reference#RequestQueueClientRequestToDelete) * [RequestQueueCollectionListResult](/api/client/js/reference#RequestQueueCollectionListResult) * [RequestQueueRequestsAsyncIterable](/api/client/js/reference#RequestQueueRequestsAsyncIterable) * [ReturnTypeFromOptions](/api/client/js/reference#ReturnTypeFromOptions) * [RunChargeOptions](/api/client/js/reference#RunChargeOptions) * [ScheduleAction](/api/client/js/reference#ScheduleAction) * [ScheduleCreateOrUpdateData](/api/client/js/reference#ScheduleCreateOrUpdateData) * [TaskList](/api/client/js/reference#TaskList) * [TaskStartOptions](/api/client/js/reference#TaskStartOptions) * [TaskUpdateData](/api/client/js/reference#TaskUpdateData) * [WebhookCondition](/api/client/js/reference#WebhookCondition) * [WebhookEventType](/api/client/js/reference#WebhookEventType) * [WebhookUpdateData](/api/client/js/reference#WebhookUpdateData) Type Aliases[](#Type Aliases) ------------------------------ ### [](#ActorChargeEvents) [](https://github.com/apify/apify-client-js/blob/43985d7/src/resource_clients/actor.ts#L503) ActorChargeEvents ActorChargeEvents: Record ### [](#ActorCollectionListResult) [](https://github.com/apify/apify-client-js/blob/43985d7/src/resource_clients/actor_collection.ts#L59) ActorCollectionListResult ActorCollectionListResult: [PaginatedList](/api/client/js/reference/interface/PaginatedList) <[ActorCollectionListItem](/api/client/js/reference/interface/ActorCollectionListItem) \> ### [](#ActorRunPricingInfo) [](https://github.com/apify/apify-client-js/blob/43985d7/src/resource_clients/actor.ts#L513) ActorRunPricingInfo ActorRunPricingInfo: [PricePerEventActorPricingInfo](/api/client/js/reference/interface/PricePerEventActorPricingInfo) | [PricePerDatasetItemActorPricingInfo](/api/client/js/reference/interface/PricePerDatasetItemActorPricingInfo) | [FlatPricePerMonthActorPricingInfo](/api/client/js/reference/interface/FlatPricePerMonthActorPricingInfo) | [FreeActorPricingInfo](/api/client/js/reference/interface/FreeActorPricingInfo) ### [](#ActorTaggedBuilds) [](https://github.com/apify/apify-client-js/blob/43985d7/src/resource_clients/actor.ts#L271) ActorTaggedBuilds ActorTaggedBuilds: Record ### [](#ActorUpdateOptions) [](https://github.com/apify/apify-client-js/blob/43985d7/src/resource_clients/actor.ts#L279) ActorUpdateOptions ActorUpdateOptions: Partial\> ### [](#AllowedHttpMethods) [](https://github.com/apify/apify-client-js/blob/43985d7/src/resource_clients/request_queue.ts#L617) AllowedHttpMethods AllowedHttpMethods: GET | HEAD | POST | PUT | DELETE | TRACE | OPTIONS | CONNECT | PATCH ### [](#BuildCollectionClientListItem) [](https://github.com/apify/apify-client-js/blob/43985d7/src/resource_clients/build_collection.ts#L39) BuildCollectionClientListItem BuildCollectionClientListItem: Required\> & Partial\> ### [](#BuildCollectionClientListResult) [](https://github.com/apify/apify-client-js/blob/43985d7/src/resource_clients/build_collection.ts#L41) BuildCollectionClientListResult BuildCollectionClientListResult: [PaginatedList](/api/client/js/reference/interface/PaginatedList) <[BuildCollectionClientListItem](/api/client/js/reference#BuildCollectionClientListItem) \> ### [](#DatasetCollectionClientListResult) [](https://github.com/apify/apify-client-js/blob/43985d7/src/resource_clients/dataset_collection.ts#L55) DatasetCollectionClientListResult DatasetCollectionClientListResult: [PaginatedList](/api/client/js/reference/interface/PaginatedList) <[Dataset](/api/client/js/reference/interface/Dataset) \> ### [](#Dictionary) [](https://github.com/apify/apify-client-js/blob/43985d7/src/utils.ts#L249) Dictionary Dictionary: Record #### Type parameters * **T** = unknown ### [](#KeyValueStoreCollectionListResult) [](https://github.com/apify/apify-client-js/blob/43985d7/src/resource_clients/key_value_store_collection.ts#L55) KeyValueStoreCollectionListResult KeyValueStoreCollectionListResult: Omit<[KeyValueStore](/api/client/js/reference/interface/KeyValueStore) , stats\> & { username?: string } ### [](#LimitsUpdateOptions) [](https://github.com/apify/apify-client-js/blob/43985d7/src/resource_clients/user.ts#L223) LimitsUpdateOptions LimitsUpdateOptions: Pick<[Limits](/api/client/js/reference/interface/Limits) , maxMonthlyUsageUsd | dataRetentionDays\> ### [](#RequestQueueClientGetRequestResult) [](https://github.com/apify/apify-client-js/blob/43985d7/src/resource_clients/request_queue.ts#L615) RequestQueueClientGetRequestResult RequestQueueClientGetRequestResult: Omit<[RequestQueueClientListItem](/api/client/js/reference/interface/RequestQueueClientListItem) , retryCount\> ### [](#RequestQueueClientRequestToDelete) [](https://github.com/apify/apify-client-js/blob/43985d7/src/resource_clients/request_queue.ts#L613) RequestQueueClientRequestToDelete RequestQueueClientRequestToDelete: Pick<[RequestQueueClientRequestSchema](/api/client/js/reference/interface/RequestQueueClientRequestSchema) , id\> | Pick<[RequestQueueClientRequestSchema](/api/client/js/reference/interface/RequestQueueClientRequestSchema) , uniqueKey\> ### [](#RequestQueueCollectionListResult) [](https://github.com/apify/apify-client-js/blob/43985d7/src/resource_clients/request_queue_collection.ts#L50) RequestQueueCollectionListResult RequestQueueCollectionListResult: [PaginatedList](/api/client/js/reference/interface/PaginatedList) <[RequestQueue](/api/client/js/reference/interface/RequestQueue) & { username?: string }\> & { unnamed: boolean } ### [](#RequestQueueRequestsAsyncIterable) [](https://github.com/apify/apify-client-js/blob/43985d7/src/resource_clients/request_queue.ts#L619) RequestQueueRequestsAsyncIterable RequestQueueRequestsAsyncIterable: AsyncIterable #### Type parameters * **T** ### [](#ReturnTypeFromOptions) [](https://github.com/apify/apify-client-js/blob/43985d7/src/resource_clients/key_value_store.ts#L273) ReturnTypeFromOptions ReturnTypeFromOptions: Options\[stream\] extends true ? Readable : Options\[buffer\] extends true ? Buffer : JsonValue #### Type parameters * **Options**: [KeyValueClientGetRecordOptions](/api/client/js/reference/interface/KeyValueClientGetRecordOptions) ### [](#RunChargeOptions) [](https://github.com/apify/apify-client-js/blob/43985d7/src/resource_clients/run.ts#L266) RunChargeOptions RunChargeOptions: { count?: number; eventName: string; idempotencyKey?: string } #### Type declaration * ##### optionalcount?: number Defaults to 1 * ##### eventName: string Name of the event to charge. Must be defined in the Actor's pricing info else the API will throw. * ##### optionalidempotencyKey?: string Defaults to runId-eventName-timestamp ### [](#ScheduleAction) [](https://github.com/apify/apify-client-js/blob/43985d7/src/resource_clients/schedule.ts#L115) ScheduleAction ScheduleAction: [ScheduleActionRunActor](/api/client/js/reference/interface/ScheduleActionRunActor) | [ScheduleActionRunActorTask](/api/client/js/reference/interface/ScheduleActionRunActorTask) ### [](#ScheduleCreateOrUpdateData) [](https://github.com/apify/apify-client-js/blob/43985d7/src/resource_clients/schedule.ts#L89) ScheduleCreateOrUpdateData ScheduleCreateOrUpdateData: Partial & { actions: DistributiveOptional<[ScheduleAction](/api/client/js/reference#ScheduleAction) , id\>\[\] }\> ### [](#TaskList) [](https://github.com/apify/apify-client-js/blob/43985d7/src/resource_clients/task_collection.ts#L53) TaskList TaskList: Omit<[Task](/api/client/js/reference/interface/Task) , options | input\> ### [](#TaskStartOptions) [](https://github.com/apify/apify-client-js/blob/43985d7/src/resource_clients/task.ts#L235) TaskStartOptions TaskStartOptions: Omit<[ActorStartOptions](/api/client/js/reference/interface/ActorStartOptions) , contentType\> ### [](#TaskUpdateData) [](https://github.com/apify/apify-client-js/blob/43985d7/src/resource_clients/task.ts#L219) TaskUpdateData TaskUpdateData: Partial\> ### [](#WebhookCondition) [](https://github.com/apify/apify-client-js/blob/43985d7/src/resource_clients/webhook.ts#L128) WebhookCondition WebhookCondition: [WebhookAnyRunOfActorCondition](/api/client/js/reference/interface/WebhookAnyRunOfActorCondition) | [WebhookAnyRunOfActorTaskCondition](/api/client/js/reference/interface/WebhookAnyRunOfActorTaskCondition) | [WebhookCertainRunCondition](/api/client/js/reference/interface/WebhookCertainRunCondition) ### [](#WebhookEventType) [](https://github.com/apify/apify-client-js/blob/43985d7/src/resource_clients/webhook.ts#L126) WebhookEventType WebhookEventType: typeof WEBHOOK\_EVENT\_TYPES\[keyof typeof WEBHOOK\_EVENT\_TYPES\] ### [](#WebhookUpdateData) [](https://github.com/apify/apify-client-js/blob/43985d7/src/resource_clients/webhook.ts#L105) WebhookUpdateData WebhookUpdateData: Partial\> & [WebhookIdempotencyKey](/api/client/js/reference/interface/WebhookIdempotencyKey) **Page Options** Hide Inherited * [ActorChargeEvents](#ActorChargeEvents) * [ActorCollectionListResult](#ActorCollectionListResult) * [ActorRunPricingInfo](#ActorRunPricingInfo) * [ActorTaggedBuilds](#ActorTaggedBuilds) * [ActorUpdateOptions](#ActorUpdateOptions) * [AllowedHttpMethods](#AllowedHttpMethods) * [BuildCollectionClientListItem](#BuildCollectionClientListItem) * [BuildCollectionClientListResult](#BuildCollectionClientListResult) * [DatasetCollectionClientListResult](#DatasetCollectionClientListResult) * [Dictionary](#Dictionary) * [KeyValueStoreCollectionListResult](#KeyValueStoreCollectionListResult) * [LimitsUpdateOptions](#LimitsUpdateOptions) * [RequestQueueClientGetRequestResult](#RequestQueueClientGetRequestResult) * [RequestQueueClientRequestToDelete](#RequestQueueClientRequestToDelete) * [RequestQueueCollectionListResult](#RequestQueueCollectionListResult) * [RequestQueueRequestsAsyncIterable](#RequestQueueRequestsAsyncIterable) * [ReturnTypeFromOptions](#ReturnTypeFromOptions) * [RunChargeOptions](#RunChargeOptions) * [ScheduleAction](#ScheduleAction) * [ScheduleCreateOrUpdateData](#ScheduleCreateOrUpdateData) * [TaskList](#TaskList) * [TaskStartOptions](#TaskStartOptions) * [TaskUpdateData](#TaskUpdateData) * [WebhookCondition](#WebhookCondition) * [WebhookEventType](#WebhookEventType) * [WebhookUpdateData](#WebhookUpdateData) --- # Getting started | API client for JavaScript | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for API client for JavaScript | Apify Documentation **2.10**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/api/client/js/docs) ** (2.11). Version: 2.10 On this page `apify-client` is the official library to access the [Apify REST API](https://docs.apify.com/api/v2) from your JavaScript/TypeScript applications. It runs both in Node.js and browser and provides useful features like automatic retries and convenience functions that improve the experience of using the Apify API. All requests and responses (including errors) are encoded in JSON format with UTF-8 encoding. Pre-requisites[​](#pre-requisites "Direct link to heading") ------------------------------------------------------------ `apify-client` requires Node.js version 16 or higher. Node.js is available for download on the [official website](https://nodejs.org/) . Check for your current node version by running: node -v Installation[​](#installation "Direct link to heading") -------------------------------------------------------- You can install the client via [NPM](https://www.npmjs.com/) or use any other package manager of your choice. * NPM * Yarn * PNPM * Bun npm i apify-client yarn add apify-client pnpm add apify-client bun add apify-client Authentication and Initialization[​](#authentication-and-initialization "Direct link to heading") -------------------------------------------------------------------------------------------------- To use the client, you need an [API token](https://docs.apify.com/platform/integrations/api#api-token) . You can find your token under [Integrations](https://console.apify.com/account/integrations) tab in Apify Console. Copy the token and initialize the client by providing the token (`MY-APIFY-TOKEN`) as a parameter to the `ApifyClient` constructor. // import Apify clientimport { ApifyClient } from 'apify-client';// Client initialization with the API tokenconst client = new ApifyClient({ token: 'MY-APIFY-TOKEN',}); Secure access The API token is used to authorize your requests to the Apify API. You can be charged for the usage of the underlying services, so do not share your API token with untrusted parties or expose it on the client side of your applications Quick start[​](#quick-start "Direct link to heading") ------------------------------------------------------ One of the most common use cases is starting [Actors](https://docs.apify.com/platform/actors) (serverless programs running in the [Apify cloud](https://docs.apify.com/platform) ) and getting results from their [datasets](https://docs.apify.com/platform/storage/dataset) (storage) after they finish the job (usually scraping, automation processes or data processing). import { ApifyClient } from 'apify-client';const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });// Starts an Actor and waits for it to finishconst { defaultDatasetId } = await client.actor('username/actor-name').call();// Lists items from the Actor's datasetconst { items } = await client.dataset(defaultDatasetId).listItems(); ### Running Actors[​](#running-actors "Direct link to heading") To start an Actor, you can use the [ActorClient](/api/client/js/reference/class/ActorClient) (`client.actor()`) and pass the Actor's ID (e.g. `john-doe/my-cool-actor`) to define which Actor you want to run. The Actor's ID is a combination of the username and the Actor owner’s username. You can run both your own Actors and [Actors from Apify Store](https://docs.apify.com/platform/actors/running/actors-in-store) . #### Passing input to the Actor[​](#passing-input-to-the-actor "Direct link to heading") To define the Actor's input, you can pass an object to the [`call()`](/api/client/js/reference/class/ActorClient#call) method. The input object can be any JSON object that the Actor expects (respects the Actor's [input schema](https://docs.apify.com/platform/actors/development/actor-definition/input-schema) ). The input object is used to pass configuration to the Actor, such as URLs to scrape, search terms, or any other data. import { ApifyClient } from 'apify-client';const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });// Runs an Actor with an input and waits for it to finish.const { defaultDatasetId } = await client.actor('username/actor-name').call({ some: 'input',}); ### Getting results from the dataset[​](#getting-results-from-the-dataset "Direct link to heading") To get the results from the dataset, you can use the [DatasetClient](/api/client/js/reference/class/DatasetClient) (`client.dataset()`) and [`listItems()`](/api/client/js/reference/class/DatasetClient#listItems) method. You need to pass the dataset ID to define which dataset you want to access. You can get the dataset ID from the Actor's run object (represented by `defaultDatasetId`). import { ApifyClient } from 'apify-client';const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });// Lists items from the Actor's dataset.const { items } = await client.dataset('dataset-id').listItems(); Dataset access Running an Actor might take time, depending on the Actor's complexity and the amount of data it processes. If you want only to get data and have an immediate response you should access the existing dataset of the finished [Actor run](https://docs.apify.com/platform/actors/running/runs-and-builds#runs) . Usage concepts[​](#usage-concepts "Direct link to heading") ------------------------------------------------------------ The `ApifyClient` interface follows a generic pattern that applies to all of its components. By calling individual methods of `ApifyClient`, specific clients that target individual API resources are created. There are two types of those clients: * [`actorClient`](/api/client/js/reference/class/ActorClient) : a client for the management of a single resource * [`actorCollectionClient`](/api/client/js/reference/class/ActorCollectionClient) : a client for the collection of resources import { ApifyClient } from 'apify-client';const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });// Collection clients do not require a parameter.const actorCollectionClient = client.actors();// Creates an actor with the name: my-actor.const myActor = await actorCollectionClient.create({ name: 'my-actor-name' });// List all your used Actors (both own and from Apify Store)const { items } = await actorCollectionClient.list(); Resource identification The resource ID can be either the `id` of the said resource, or a combination of your `username/resource-name`. import { ApifyClient } from 'apify-client';const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });// Resource clients accept an ID of the resource.const actorClient = client.actor('username/actor-name');// Fetches the john-doe/my-actor object from the API.const myActor = await actorClient.get();// Starts the run of john-doe/my-actor and returns the Run object.const myActorRun = await actorClient.start(); ### Nested clients[​](#nested-clients "Direct link to heading") Sometimes clients return other clients. That's to simplify working with nested collections, such as runs of a given Actor. import { ApifyClient } from 'apify-client';const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });const actorClient = client.actor('username/actor-name');const runsClient = actorClient.runs();// Lists the last 10 runs of your Actor.const { items } = await runsClient.list({ limit: 10, desc: true});// Select the last run of your Actor that finished// with a SUCCEEDED status.const lastSucceededRunClient = actorClient.lastRun({ status: 'SUCCEEDED' });// Fetches items from the run's dataset.const { items } = await lastSucceededRunClient.dataset() .listItems(); The quick access to `dataset` and other storage directly from the run client can be used with the [`lastRun()`](/api/client/js/reference/class/ActorClient#lastRun)  method. Features[​](#features "Direct link to heading") ------------------------------------------------ Based on the endpoint, the client automatically extracts the relevant data and returns it in the expected format. Date strings are automatically converted to `Date` objects. For exceptions, the client throws an [`ApifyApiError`](/api/client/js/reference/class/ApifyApiError) , which wraps the plain JSON errors returned by API and enriches them with other contexts for easier debugging. import { ApifyClient } from 'apify-client';const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });try { const { items } = await client.dataset("non-existing-dataset-id").listItems();} catch (error) { // The error is an instance of ApifyApiError const { message, type, statusCode, clientMethod, path } = error; // Log error for easier debugging console.log({ message, statusCode, clientMethod, type });} ### Retries with exponential backoff[​](#retries-with-exponential-backoff "Direct link to heading") Network communication sometimes fails. That's a given. The client will automatically retry requests that failed due to a network error, an internal error of the Apify API (HTTP 500+), or a rate limit error (HTTP 429). By default, it will retry up to 8 times. The first retry will be attempted after ~500ms, the second after ~1000ms, and so on. You can configure those parameters using the `maxRetries` and `minDelayBetweenRetriesMillis` options of the `ApifyClient` constructor. import { ApifyClient } from 'apify-client';const client = new ApifyClient({ token: 'MY-APIFY-TOKEN', maxRetries: 8, minDelayBetweenRetriesMillis: 500, // 0.5s timeoutSecs: 360 // 6 mins}); ### Convenience functions and options[​](#convenience-functions-and-options "Direct link to heading") Some actions can't be performed by the API itself, such as indefinite waiting for an Actor run to finish (because of network timeouts). The client provides convenient `call()` and `waitForFinish()` functions that do that. If the limit is reached, the returned promise is resolved to a run object that will have status `READY` or `RUNNING` and it will not contain the Actor run output. [Key-value store](https://docs.apify.com/platform/storage/key-value-store) records can be retrieved as objects, buffers, or streams via the respective options, dataset items can be fetched as individual objects or serialized data. import { ApifyClient } from 'apify-client';const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });// Starts an Actor and waits for it to finish.const finishedActorRun = await client.actor('username/actor-name').call();// Starts an Actor and waits maximum 60s for the finish const { status } = await client.actor('username/actor-name').start({ waitForFinish: 60, // 1 minute}); ### Pagination[​](#pagination "Direct link to heading") Most methods named `list` or `listSomething` return a [`Promise`](/api/client/js/reference/interface/PaginatedList) . There are some exceptions though, like `listKeys` or `listHead` which paginate differently. The results you're looking for are always stored under `items` and you can use the `limit` property to get only a subset of results. Other props are also available, depending on the method. import { ApifyClient } from 'apify-client';const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });// Resource clients accept an ID of the resource.const datasetClient = client.dataset('dataset-id');// Number of items per pageconst limit = 1000;// Initial offsetlet offset = 0; // Array to store all itemslet allItems = []; while (true) { const { items, total } = await datasetClient.listItems({ limit, offset }); console.log(`Fetched ${items.length} items`); // Merge new items with other already loaded items allItems.push(...items); // If there are no more items to fetch, exit the loading if (offset + limit >= total) { break; } offset += limit;}console.log(`Overall fetched ${allItems.length} items`); * [Pre-requisites](#pre-requisites) * [Installation](#installation) * [Authentication and Initialization](#authentication-and-initialization) * [Quick start](#quick-start) * [Running Actors](#running-actors) * [Getting results from the dataset](#getting-results-from-the-dataset) * [Usage concepts](#usage-concepts) * [Nested clients](#nested-clients) * [Features](#features) * [Retries with exponential backoff](#retries-with-exponential-backoff) * [Convenience functions and options](#convenience-functions-and-options) * [Pagination](#pagination) --- # Getting started | API client for JavaScript | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for API client for JavaScript | Apify Documentation **2.9**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/api/client/js/docs) ** (2.11). Version: 2.9 On this page `apify-client` is the official library to access the [Apify REST API](https://docs.apify.com/api/v2) from your JavaScript/TypeScript applications. It runs both in Node.js and browser and provides useful features like automatic retries and convenience functions that improve the experience of using the Apify API. All requests and responses (including errors) are encoded in JSON format with UTF-8 encoding. Pre-requisites[​](#pre-requisites "Direct link to heading") ------------------------------------------------------------ `apify-client` requires Node.js version 16 or higher. Node.js is available for download on the [official website](https://nodejs.org/) . Check for your current node version by running: node -v Installation[​](#installation "Direct link to heading") -------------------------------------------------------- You can install the client via [NPM](https://www.npmjs.com/) or use any other package manager of your choice. * NPM * Yarn * PNPM * Bun npm i apify-client yarn add apify-client pnpm add apify-client bun add apify-client Authentication and Initialization[​](#authentication-and-initialization "Direct link to heading") -------------------------------------------------------------------------------------------------- To use the client, you need an [API token](https://docs.apify.com/platform/integrations/api#api-token) . You can find your token under [Integrations](https://console.apify.com/account/integrations) tab in Apify Console. Copy the token and initialize the client by providing the token (`MY-APIFY-TOKEN`) as a parameter to the `ApifyClient` constructor. // import Apify clientimport { ApifyClient } from 'apify-client';// Client initialization with the API tokenconst client = new ApifyClient({ token: 'MY-APIFY-TOKEN',}); Secure access The API token is used to authorize your requests to the Apify API. You can be charged for the usage of the underlying services, so do not share your API token with untrusted parties or expose it on the client side of your applications Quick start[​](#quick-start "Direct link to heading") ------------------------------------------------------ One of the most common use cases is starting [Actors](https://docs.apify.com/platform/actors) (serverless programs running in the [Apify cloud](https://docs.apify.com/platform) ) and getting results from their [datasets](https://docs.apify.com/platform/storage/dataset) (storage) after they finish the job (usually scraping, automation processes or data processing). import { ApifyClient } from 'apify-client';const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });// Starts an Actor and waits for it to finishconst { defaultDatasetId } = await client.actor('username/actor-name').call();// Lists items from the Actor's datasetconst { items } = await client.dataset(defaultDatasetId).listItems(); ### Running Actors[​](#running-actors "Direct link to heading") To start an Actor, you can use the [ActorClient](/api/client/js/reference/class/ActorClient) (`client.actor()`) and pass the Actor's ID (e.g. `john-doe/my-cool-actor`) to define which Actor you want to run. The Actor's ID is a combination of the username and the Actor owner’s username. You can run both your own Actors and [Actors from Apify Store](https://docs.apify.com/platform/actors/running/actors-in-store) . #### Passing input to the Actor[​](#passing-input-to-the-actor "Direct link to heading") To define the Actor's input, you can pass an object to the [`call()`](/api/client/js/reference/class/ActorClient#call) method. The input object can be any JSON object that the Actor expects (respects the Actor's [input schema](https://docs.apify.com/platform/actors/development/actor-definition/input-schema) ). The input object is used to pass configuration to the Actor, such as URLs to scrape, search terms, or any other data. import { ApifyClient } from 'apify-client';const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });// Runs an Actor with an input and waits for it to finish.const { defaultDatasetId } = await client.actor('username/actor-name').call({ some: 'input',}); ### Getting results from the dataset[​](#getting-results-from-the-dataset "Direct link to heading") To get the results from the dataset, you can use the [DatasetClient](/api/client/js/reference/class/DatasetClient) (`client.dataset()`) and [`listItems()`](/api/client/js/reference/class/DatasetClient#listItems) method. You need to pass the dataset ID to define which dataset you want to access. You can get the dataset ID from the Actor's run object (represented by `defaultDatasetId`). import { ApifyClient } from 'apify-client';const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });// Lists items from the Actor's dataset.const { items } = await client.dataset('dataset-id').listItems(); Dataset access Running an Actor might take time, depending on the Actor's complexity and the amount of data it processes. If you want only to get data and have an immediate response you should access the existing dataset of the finished [Actor run](https://docs.apify.com/platform/actors/running/runs-and-builds#runs) . Usage concepts[​](#usage-concepts "Direct link to heading") ------------------------------------------------------------ The `ApifyClient` interface follows a generic pattern that applies to all of its components. By calling individual methods of `ApifyClient`, specific clients that target individual API resources are created. There are two types of those clients: * [`actorClient`](/api/client/js/reference/class/ActorClient) : a client for the management of a single resource * [`actorCollectionClient`](/api/client/js/reference/class/ActorCollectionClient) : a client for the collection of resources import { ApifyClient } from 'apify-client';const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });// Collection clients do not require a parameter.const actorCollectionClient = client.actors();// Creates an actor with the name: my-actor.const myActor = await actorCollectionClient.create({ name: 'my-actor-name' });// List all your used Actors (both own and from Apify Store)const { items } = await actorCollectionClient.list(); Resource identification The resource ID can be either the `id` of the said resource, or a combination of your `username/resource-name`. import { ApifyClient } from 'apify-client';const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });// Resource clients accept an ID of the resource.const actorClient = client.actor('username/actor-name');// Fetches the john-doe/my-actor object from the API.const myActor = await actorClient.get();// Starts the run of john-doe/my-actor and returns the Run object.const myActorRun = await actorClient.start(); ### Nested clients[​](#nested-clients "Direct link to heading") Sometimes clients return other clients. That's to simplify working with nested collections, such as runs of a given Actor. import { ApifyClient } from 'apify-client';const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });const actorClient = client.actor('username/actor-name');const runsClient = actorClient.runs();// Lists the last 10 runs of your Actor.const { items } = await runsClient.list({ limit: 10, desc: true});// Select the last run of your Actor that finished// with a SUCCEEDED status.const lastSucceededRunClient = actorClient.lastRun({ status: 'SUCCEEDED' });// Fetches items from the run's dataset.const { items } = await lastSucceededRunClient.dataset() .listItems(); The quick access to `dataset` and other storage directly from the run client can be used with the [`lastRun()`](/api/client/js/reference/class/ActorClient#lastRun)  method. Features[​](#features "Direct link to heading") ------------------------------------------------ Based on the endpoint, the client automatically extracts the relevant data and returns it in the expected format. Date strings are automatically converted to `Date` objects. For exceptions, the client throws an [`ApifyApiError`](/api/client/js/reference/class/ApifyApiError) , which wraps the plain JSON errors returned by API and enriches them with other contexts for easier debugging. import { ApifyClient } from 'apify-client';const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });try { const { items } = await client.dataset("non-existing-dataset-id").listItems();} catch (error) { // The error is an instance of ApifyApiError const { message, type, statusCode, clientMethod, path } = error; // Log error for easier debugging console.log({ message, statusCode, clientMethod, type });} ### Retries with exponential backoff[​](#retries-with-exponential-backoff "Direct link to heading") Network communication sometimes fails. That's a given. The client will automatically retry requests that failed due to a network error, an internal error of the Apify API (HTTP 500+), or a rate limit error (HTTP 429). By default, it will retry up to 8 times. The first retry will be attempted after ~500ms, the second after ~1000ms, and so on. You can configure those parameters using the `maxRetries` and `minDelayBetweenRetriesMillis` options of the `ApifyClient` constructor. import { ApifyClient } from 'apify-client';const client = new ApifyClient({ token: 'MY-APIFY-TOKEN', maxRetries: 8, minDelayBetweenRetriesMillis: 500, // 0.5s timeoutSecs: 360 // 6 mins}); ### Convenience functions and options[​](#convenience-functions-and-options "Direct link to heading") Some actions can't be performed by the API itself, such as indefinite waiting for an Actor run to finish (because of network timeouts). The client provides convenient `call()` and `waitForFinish()` functions that do that. If the limit is reached, the returned promise is resolved to a run object that will have status `READY` or `RUNNING` and it will not contain the Actor run output. [Key-value store](https://docs.apify.com/platform/storage/key-value-store) records can be retrieved as objects, buffers, or streams via the respective options, dataset items can be fetched as individual objects or serialized data. import { ApifyClient } from 'apify-client';const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });// Starts an Actor and waits for it to finish.const finishedActorRun = await client.actor('username/actor-name').call();// Starts an Actor and waits maximum 60s for the finish const { status } = await client.actor('username/actor-name').start({ waitForFinish: 60, // 1 minute}); ### Pagination[​](#pagination "Direct link to heading") Most methods named `list` or `listSomething` return a [`Promise`](/api/client/js/reference/interface/PaginatedList) . There are some exceptions though, like `listKeys` or `listHead` which paginate differently. The results you're looking for are always stored under `items` and you can use the `limit` property to get only a subset of results. Other props are also available, depending on the method. import { ApifyClient } from 'apify-client';const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });// Resource clients accept an ID of the resource.const datasetClient = client.dataset('dataset-id');// Number of items per pageconst limit = 1000;// Initial offsetlet offset = 0; // Array to store all itemslet allItems = []; while (true) { const { items, total } = await datasetClient.listItems({ limit, offset }); console.log(`Fetched ${items.length} items`); // Merge new items with other already loaded items allItems.push(...items); // If there are no more items to fetch, exit the loading if (offset + limit >= total) { break; } offset += limit;}console.log(`Overall fetched ${allItems.length} items`); * [Pre-requisites](#pre-requisites) * [Installation](#installation) * [Authentication and Initialization](#authentication-and-initialization) * [Quick start](#quick-start) * [Running Actors](#running-actors) * [Getting results from the dataset](#getting-results-from-the-dataset) * [Usage concepts](#usage-concepts) * [Nested clients](#nested-clients) * [Features](#features) * [Retries with exponential backoff](#retries-with-exponential-backoff) * [Convenience functions and options](#convenience-functions-and-options) * [Pagination](#pagination) --- # Webhook collection - Introduction | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) The API endpoint in this section allows you to get a list of webhooks of a specific Actor. [Get list of webhooks\ --------------------\ \ `/acts/{actorId}/webhooks`](/api/v2/act-webhooks-get) --- # Metamorph run | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Metamorph run ============= POST /v2/acts/:actorId/runs/:runId/metamorph --------------------------------------- deprecated This endpoint has been deprecated and may be replaced or removed in future versions of the API. **\[DEPRECATED\]** API endpoints related to run of the Actor were moved under new namespace [`actor-runs`](#/reference/actor-runs) .Transforms an Actor run into a run of another Actor with a new input. This is useful if you want to use another Actor to finish the work of your current Actor run, without the need to create a completely new run and waiting for its finish. For the users of your Actors, the metamorph operation is transparent, they will just see your Actor got the work done. There is a limit on how many times you can metamorph a single run. You can check the limit in [the Actor runtime limits](https://docs.apify.com/platform/limits#actor-limits) . Internally, the system stops the Docker container corresponding to the Actor run and starts a new container using a different Docker image. All the default storages are preserved and the new input is stored under the `INPUT-METAMORPH-1` key in the same default key-value store. For more information, see the [Actor docs](https://docs.apify.com/platform/actors/development/programming-interface/metamorph) . Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 **Response Headers** --- # Quick start | API client for JavaScript | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for API client for JavaScript | Apify Documentation **2.8**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/api/client/js/docs) ** (2.11). Version: 2.8 On this page `apify-client` is the official library to access [Apify API](https://docs.apify.com/api/v2) from your JavaScript applications. It runs both in Node.js and browser and provides useful features like automatic retries and convenience functions that improve the experience of using the Apify API. You can install the client via the [npm package](https://www.npmjs.com/package/apify-client) . To do that, simply run `npm i apify-client`. Quick Start[​](#quick-start "Direct link to heading") ------------------------------------------------------ const { ApifyClient } = require('apify-client');const client = new ApifyClient({ token: 'MY-APIFY-TOKEN',});// Starts an actor and waits for it to finish.const { defaultDatasetId } = await client.actor('john-doe/my-cool-actor').call();// Fetches results from the actor's dataset.const { items } = await client.dataset(defaultDatasetId).listItems(); * [Quick Start](#quick-start) --- # Quick start | API client for JavaScript | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for API client for JavaScript | Apify Documentation **2.7**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/api/client/js/docs) ** (2.11). Version: 2.7 On this page `apify-client` is the official library to access [Apify API](https://docs.apify.com/api/v2) from your JavaScript applications. It runs both in Node.js and browser and provides useful features like automatic retries and convenience functions that improve the experience of using the Apify API. Quick Start[​](#quick-start "Direct link to heading") ------------------------------------------------------ const { ApifyClient } = require('apify-client');const client = new ApifyClient({ token: 'MY-APIFY-TOKEN',});// Starts an actor and waits for it to finish.const { defaultDatasetId } = await client.actor('john-doe/my-cool-actor').call();// Fetches results from the actor's dataset.const { items } = await client.dataset(defaultDatasetId).listItems(); * [Quick Start](#quick-start) --- # Get list of webhooks | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Get list of webhooks ==================== GET /v2/acts/:actorId/webhooks -------------------------- Gets the list of webhooks of a specific Actor. The response is a JSON with the list of objects, where each object contains basic information about a single webhook. The endpoint supports pagination using the `limit` and `offset` parameters and it will not return more than 1000 records. By default, the records are sorted by the `createdAt` field in ascending order, to sort the records in descending order, use the `desc=1` parameter. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 **Response Headers** --- # Quick start | API client for JavaScript | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) This is documentation for API client for JavaScript | Apify Documentation **2.6**, which is no longer actively maintained. For up-to-date documentation, see the **[latest version](/api/client/js/docs) ** (2.11). Version: 2.6 On this page `apify-client` is the official library to access [Apify API](https://docs.apify.com/api/v2) from your JavaScript applications. It runs both in Node.js and browser and provides useful features like automatic retries and convenience functions that improve the experience of using the Apify API. Quick Start[​](#quick-start "Direct link to heading") ------------------------------------------------------ const { ApifyClient } = require('apify-client');const client = new ApifyClient({ token: 'MY-APIFY-TOKEN',});// Starts an actor and waits for it to finish.const { defaultDatasetId } = await client.actor('john-doe/my-cool-actor').call();// Fetches results from the actor's dataset.const { items } = await client.dataset(defaultDatasetId).listItems(); * [Quick Start](#quick-start) --- # Actor builds - Introduction | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) The API endpoints described in this section enable you to manage, and delete Apify Actor builds. Note that if any returned build object contains usage in dollars, your effective unit pricing at the time of query has been used for computation of this dollar equivalent, and hence it should be used only for informative purposes. You can learn more about platform usage in the [documentation](https://docs.apify.com/platform/actors/running/usage-and-resources#usage) . [Get user builds list\ --------------------\ \ `/actor-builds`](/api/v2/actor-builds-get) [Get build\ ---------\ \ `/actor-builds/{buildId}`](/api/v2/actor-build-get) [Delete build\ ------------\ \ `/actor-builds/{buildId}`](/api/v2/actor-build-delete) [Abort build\ -----------\ \ `/actor-builds/{buildId}/abort`](/api/v2/actor-build-abort-post) [Get log\ -------\ \ `/actor-builds/{buildId}/log`](/api/v2/actor-build-log-get) [Get OpenAPI definition\ ----------------------\ \ `/actor-builds/{buildId}/openapi.json`](/api/v2/actor-build-openapi-json-get) --- # Get user builds list | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Get user builds list ==================== GET /v2/actor-builds ---------------- Gets a list of all builds for a user. The response is a JSON array of objects, where each object contains basic information about a single build. The endpoint supports pagination using the `limit` and `offset` parameters and it will not return more than 1000 records. By default, the records are sorted by the `startedAt` field in ascending order. Therefore, you can use pagination to incrementally fetch all builds while new ones are still being started. To sort the records in descending order, use the `desc=1` parameter. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 **Response Headers** --- # Get build | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Get build ========= GET /v2/actor-builds/:buildId ------------------------- Clients[![Apify API Python Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/python.svg)](https://docs.apify.com/api/client/python/reference/class/BuildClientAsync#get) [![Apify API JavaScript Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/javascript.svg)](https://docs.apify.com/api/client/js/reference/class/BuildClient#get) Gets an object that contains all the details about a specific build of an Actor. By passing the optional `waitForFinish` parameter the API endpoint will synchronously wait for the build to finish. This is useful to avoid periodic polling when waiting for an Actor build to finish. This endpoint does not require the authentication token. Instead, calls are authenticated using a hard-to-guess ID of the build. However, if you access the endpoint without the token, certain attributes, such as `usageUsd` and `usageTotalUsd`, will be hidden. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 **Response Headers** --- # Delete build | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Delete build ============ DELETE /v2/actor-builds/:buildId ------------------------- Clients[![Apify API JavaScript Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/javascript.svg)](https://docs.apify.com/api/client/js/reference/class/BuildClient#delete) Delete the build. The build that is the current default build for the Actor cannot be deleted. Only users with build permissions for the Actor can delete builds. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 204 **Response Headers** --- # Abort build | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Abort build =========== POST /v2/actor-builds/:buildId/abort ------------------------------- Clients[![Apify API Python Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/python.svg)](https://docs.apify.com/api/client/python/reference/class/BuildClientAsync#abort) [![Apify API JavaScript Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/javascript.svg)](https://docs.apify.com/api/client/js/reference/class/BuildClient#abort) Aborts an Actor build and returns an object that contains all the details about the build. Only builds that are starting or running are aborted. For builds with status `FINISHED`, `FAILED`, `ABORTING` and `TIMED-OUT` this call does nothing. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 **Response Headers** --- # Get log | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Get log ======= GET /v2/actor-builds/:buildId/log ----------------------------- Check out [Logs](#/reference/logs) for full reference. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 **Response Headers** --- # Get user runs list | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Get user runs list ================== GET /v2/actor-runs -------------- Gets a list of all runs for a user. The response is a list of objects, where each object contains basic information about a single Actor run. The endpoint supports pagination using the `limit` and `offset` parameters and it will not return more than 1000 array elements. By default, the records are sorted by the `startedAt` field in ascending order. Therefore, you can use pagination to incrementally fetch all records while new ones are still being created. To sort the records in descending order, use `desc=1` parameter. You can also filter runs by status ([available statuses](https://docs.apify.com/platform/actors/running/runs-and-builds#lifecycle) ). Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 **Response Headers** --- # Actor runs - Introduction | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) The API endpoints described in this section enable you to manage, and delete Apify Actor runs. If any returned run object contains usage in dollars, your effective unit pricing at the time of query has been used for computation of this dollar equivalent, and hence it should be used only for informative purposes. You can learn more about platform usage in the [documentation](https://docs.apify.com/platform/actors/running/usage-and-resources#usage) . [Get user runs list\ ------------------\ \ `/actor-runs`](/api/v2/actor-runs-get) [Get run\ -------\ \ `/actor-runs/{runId}`](/api/v2/actor-run-get) [Update status message\ ---------------------\ \ `/actor-runs/{runId}`](/api/v2/actor-run-put) [Delete run\ ----------\ \ `/actor-runs/{runId}`](/api/v2/actor-run-delete) [Abort run\ ---------\ \ `/actor-runs/{runId}/abort`](/api/v2/actor-run-abort-post) [Metamorph run\ -------------\ \ `/actor-runs/{runId}/metamorph`](/api/v2/actor-run-metamorph-post) [Reboot run\ ----------\ \ `/actor-runs/{runId}/reboot`](/api/v2/actor-run-reboot-post) [Resurrect run\ -------------\ \ `/actor-runs/{runId}/resurrect`](/api/v2/post-resurrect-run) [Charge events in run\ --------------------\ \ `/actor-runs/{runId}/charge`](/api/v2/post-charge-run) --- # Get OpenAPI definition | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Get OpenAPI definition ====================== GET /v2/actor-builds/:buildId/openapi.json -------------------------------------- Get the OpenAPI definition for Actor builds. Two similar endpoints are available: * [First endpoint](/api/v2/act-openapi-json-get) : Requires both `actorId` and `buildId`. Use `default` as the `buildId` to get the OpenAPI schema for the default Actor build. * [Second endpoint](/api/v2/actor-build-openapi-json-get) : Requires only `buildId`. Get the OpenAPI definition for a specific Actor build. Authentication is based on the build's unique ID. No authentication token is required. note You can also use the [`/api/v2/act-openapi-json-get`](/api/v2/act-openapi-json-get) endpoint to get the OpenAPI definition for a build. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 **Response Headers** --- # Update status message | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Update status message ===================== PUT /v2/actor-runs/:runId --------------------- You can set a single status message on your run that will be displayed in the Apify Console UI. During an Actor run, you will typically do this in order to inform users of your Actor about the Actor's progress. The request body must contain `runId` and `statusMessage` properties. The `isStatusMessageTerminal` property is optional and it indicates if the status message is the very last one. In the absence of a status message, the platform will try to substitute sensible defaults. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 **Response Headers** --- # Get run | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Get run ======= GET /v2/actor-runs/:runId --------------------- This is not a single endpoint, but an entire group of endpoints that lets you retrieve the run or any of its default storages. The endpoints accept the same HTTP methods and query parameters as the respective storage endpoints. The base path that represents the Actor run object is: `/v2/actor-runs/{runId}{?token}` In order to access the default storages of the Actor run, i.e. log, key-value store, dataset and request queue, use the following endpoints: * `/v2/actor-runs/{runId}/log{?token}` * `/v2/actor-runs/{runId}/key-value-store{?token}` * `/v2/actor-runs/{runId}/dataset{?token}` * `/v2/actor-runs/{runId}/request-queue{?token}` These API endpoints have the same usage as the equivalent storage endpoints. For example, `/v2/actor-runs/{runId}/key-value-store` has the same HTTP method and parameters as the [Key-value store object](#/reference/key-value-stores/store-object) endpoint. Additionally, each of the above API endpoints supports all sub-endpoints of the original one: #### Log[​](#log "Direct link to Log") * `/v2/actor-runs/{runId}/log` [Log](#/reference/logs) #### Key-value store[​](#key-value-store "Direct link to Key-value store") * `/v2/actor-runs/{runId}/key-value-store/keys{?token}` [Key collection](#/reference/key-value-stores/key-collection) * `/v2/actor-runs/{runId}/key-value-store/records/{recordKey}{?token}` [Record](#/reference/key-value-stores/record) #### Dataset[​](#dataset "Direct link to Dataset") * `/v2/actor-runs/{runId}/dataset/items{?token}` [Item collection](#/reference/datasets/item-collection) #### Request queue[​](#request-queue "Direct link to Request queue") * `/v2/actor-runs/{runId}/request-queue/requests{?token}` [Request collection](#/reference/request-queues/request-collection) * `/v2/actor-runs/{runId}/request-queue/requests/{requestId}{?token}` [Request collection](#/reference/request-queues/request) * `/v2/actor-runs/{runId}/request-queue/head{?token}` [Queue head](#/reference/request-queues/queue-head) For example, to download data from a dataset of the Actor run in XML format, send HTTP GET request to the following URL: https://api.apify.com/v2/actor-runs/{runId}/dataset/items?format=xml In order to save new items to the dataset, send HTTP POST request with JSON payload to the same URL. Gets an object that contains all the details about a specific run of an Actor. By passing the optional `waitForFinish` parameter the API endpoint will synchronously wait for the run to finish. This is useful to avoid periodic polling when waiting for Actor run to complete. This endpoint does not require the authentication token. Instead, calls are authenticated using a hard-to-guess ID of the run. However, if you access the endpoint without the token, certain attributes, such as `usageUsd` and `usageTotalUsd`, will be hidden. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 **Response Headers** --- # Delete run | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Delete run ========== DELETE /v2/actor-runs/:runId --------------------- Clients[![Apify API JavaScript Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/javascript.svg)](https://docs.apify.com/api/client/js/reference/class/RunClient#delete) Delete the run. Only finished runs can be deleted. Only the person or organization that initiated the run can delete it. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 204 **Response Headers** --- # Metamorph run | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Metamorph run ============= POST /v2/actor-runs/:runId/metamorph ------------------------------- Clients[![Apify API Python Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/python.svg)](https://docs.apify.com/api/client/python/reference/class/RunClientAsync#metamorph) [![Apify API JavaScript Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/javascript.svg)](https://docs.apify.com/api/client/js/reference/class/RunClient#metamorph) Transforms an Actor run into a run of another Actor with a new input. This is useful if you want to use another Actor to finish the work of your current Actor run, without the need to create a completely new run and waiting for its finish. For the users of your Actors, the metamorph operation is transparent, they will just see your Actor got the work done. Internally, the system stops the Docker container corresponding to the Actor run and starts a new container using a different Docker image. All the default storages are preserved and the new input is stored under the `INPUT-METAMORPH-1` key in the same default key-value store. For more information, see the [Actor docs](https://docs.apify.com/platform/actors/development/programming-interface/metamorph) . Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 **Response Headers** --- # Abort run | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Abort run ========= POST /v2/actor-runs/:runId/abort --------------------------- Clients[![Apify API Python Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/python.svg)](https://docs.apify.com/api/client/python/reference/class/RunClientAsync#abort) [![Apify API JavaScript Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/javascript.svg)](https://docs.apify.com/api/client/js/reference/class/RunClient#abort) Aborts an Actor run and returns an object that contains all the details about the run. Only runs that are starting or running are aborted. For runs with status `FINISHED`, `FAILED`, `ABORTING` and `TIMED-OUT` this call does nothing. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 **Response Headers** --- # Reboot run | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Reboot run ========== POST /v2/actor-runs/:runId/reboot ---------------------------- Clients[![Apify API Python Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/python.svg)](https://docs.apify.com/api/client/python/reference/class/RunClientAsync#reboot) [![Apify API JavaScript Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/javascript.svg)](https://docs.apify.com/api/client/js/reference/class/RunClient#reboot) Reboots an Actor run and returns an object that contains all the details about the rebooted run. Only runs that are running, i.e. runs with status `RUNNING` can be rebooted. The run's container will be restarted, so any data not persisted in the key-value store, dataset, or request queue will be lost. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 **Response Headers** --- # Charge events in run | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Charge events in run ==================== POST /v2/actor-runs/:runId/charge ---------------------------- Clients[![Apify API Python Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/python.svg)](https://docs.apify.com/api/client/python/reference/class/RunClientAsync#charge) [![Apify API JavaScript Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/javascript.svg)](https://docs.apify.com/api/client/js/reference/class/RunClient#charge) Charge for events in the run of your [pay per event Actor](https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event) . The event you are charging for must be one of the configured events in your Actor. If the Actor is not set up as pay per event, or if the event is not configured, the endpoint will return an error. The endpoint must be called from the Actor run itself, with the same API token that the run was started with. note Pay per events Actors are still in alpha. Please, reach out to us with any questions or feedback. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 201 The charge was successful. Note that you still have to make sure in your Actor that the total charge for the run respects the maximum value set by the user, as the API does not check this. Above the limit, the charges reported as successful in API will not be added to your payouts, but you will still bear the associated costs. Use the Apify charge manager or SDK to avoid having to deal with this manually. --- # Resurrect run | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Resurrect run ============= POST /v2/actor-runs/:runId/resurrect ------------------------------- Clients[![Apify API Python Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/python.svg)](https://docs.apify.com/api/client/python/reference/class/RunClientAsync#resurrect) [![Apify API JavaScript Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/javascript.svg)](https://docs.apify.com/api/client/js/reference/class/RunClient#resurrect) Resurrects a finished Actor run and returns an object that contains all the details about the resurrected run. Only finished runs, i.e. runs with status `FINISHED`, `FAILED`, `ABORTED` and `TIMED-OUT` can be resurrected. Run status will be updated to RUNNING and its container will be restarted with the same storages (the same behaviour as when the run gets migrated to the new server). For more information, see the [Actor docs](https://docs.apify.com/platform/actors/running/runs-and-builds#resurrection-of-finished-run) . Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 **Response Headers** --- # Actor tasks - Introduction | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) The API endpoints described in this section enable you to create, manage, delete, and run Apify Actor tasks. For more information, see the [Actor tasts documentation](https://docs.apify.com/platform/actors/running/tasks) . note For all the API endpoints that accept the `actorTaskId` parameter to specify a task, you can pass either the task ID (e.g. `HG7ML7M8z78YcAPEB`) or a tilde-separated username of the task's owner and the task's name (e.g. `janedoe~my-task`). Some of the API endpoints return run objects. If any such run object contains usage in dollars, your effective unit pricing at the time of query has been used for computation of this dollar equivalent, and hence it should be used only for informative purposes. You can learn more about platform usage in the [documentation](https://docs.apify.com/platform/actors/running/usage-and-resources#usage) . [Get list of tasks\ -----------------\ \ `/actor-tasks`](/api/v2/actor-tasks-get) [Create task\ -----------\ \ `/actor-tasks`](/api/v2/actor-tasks-post) [Get task\ --------\ \ `/actor-tasks/{actorTaskId}`](/api/v2/actor-task-get) [Update task\ -----------\ \ `/actor-tasks/{actorTaskId}`](/api/v2/actor-task-put) [Delete task\ -----------\ \ `/actor-tasks/{actorTaskId}`](/api/v2/actor-task-delete) [Get task input\ --------------\ \ `/actor-tasks/{actorTaskId}/input`](/api/v2/actor-task-input-get) [Update task input\ -----------------\ \ `/actor-tasks/{actorTaskId}/input`](/api/v2/actor-task-input-put) [Get list of webhooks\ --------------------\ \ `/actor-tasks/{actorTaskId}/webhooks`](/api/v2/actor-task-webhooks-get) [Get list of task runs\ ---------------------\ \ `/actor-tasks/{actorTaskId}/runs`](/api/v2/actor-task-runs-get) [Run task\ --------\ \ `/actor-tasks/{actorTaskId}/runs`](/api/v2/actor-task-runs-post) [Run task synchronously\ ----------------------\ \ `/actor-tasks/{actorTaskId}/run-sync`](/api/v2/actor-task-run-sync-get) [Run task synchronously\ ----------------------\ \ `/actor-tasks/{actorTaskId}/run-sync`](/api/v2/actor-task-run-sync-post) [Run task synchronously and get dataset items\ --------------------------------------------\ \ `/actor-tasks/{actorTaskId}/run-sync-get-dataset-items`](/api/v2/actor-task-run-sync-get-dataset-items-get) [Run task synchronously and get dataset items\ --------------------------------------------\ \ `/actor-tasks/{actorTaskId}/run-sync-get-dataset-items`](/api/v2/actor-task-run-sync-get-dataset-items-post) --- # Get list of tasks | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Get list of tasks ================= GET /v2/actor-tasks --------------- Clients[![Apify API Python Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/python.svg)](https://docs.apify.com/api/client/python/reference/class/TaskCollectionClientAsync#list) [![Apify API JavaScript Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/javascript.svg)](https://docs.apify.com/api/client/js/reference/class/TaskCollectionClient#list) Gets the complete list of tasks that a user has created or used. The response is a list of objects in which each object contains essential information about a single task. The endpoint supports pagination using the `limit` and `offset` parameters, and it does not return more than a 1000 records. By default, the records are sorted by the `createdAt` field in ascending order; therefore you can use pagination to incrementally fetch all tasks while new ones are still being created. To sort the records in descending order, use the `desc=1` parameter. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 **Response Headers** --- # Create task | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Create task =========== POST /v2/actor-tasks --------------- Clients[![Apify API Python Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/python.svg)](https://docs.apify.com/api/client/python/reference/class/TaskCollectionClientAsync#create) [![Apify API JavaScript Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/javascript.svg)](https://docs.apify.com/api/client/js/reference/class/TaskCollectionClient#create) Create a new task with settings specified by the object passed as JSON in the POST payload. The response is the full task object as returned by the [Get task](#/reference/tasks/task-object/get-task) endpoint. The request needs to specify the `Content-Type: application/json` HTTP header! When providing your API authentication token, we recommend using the request's `Authorization` header, rather than the URL. ([More info](#/introduction/authentication) ). Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 201 **Response Headers** **Location** --- # Get task | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Get task ======== GET /v2/actor-tasks/:actorTaskId ---------------------------- Clients[![Apify API Python Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/python.svg)](https://docs.apify.com/api/client/python/reference/class/TaskClientAsync#get) [![Apify API JavaScript Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/javascript.svg)](https://docs.apify.com/api/client/js/reference/class/TaskClient#get) Get an object that contains all the details about a task. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 **Response Headers** --- # Delete task | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Delete task =========== DELETE /v2/actor-tasks/:actorTaskId ---------------------------- Clients[![Apify API JavaScript Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/javascript.svg)](https://docs.apify.com/api/client/js/reference/class/TaskClient#delete) Delete the task specified through the `actorTaskId` parameter. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 204 **Response Headers** --- # Update task | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Update task =========== PUT /v2/actor-tasks/:actorTaskId ---------------------------- Clients[![Apify API Python Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/python.svg)](https://docs.apify.com/api/client/python/reference/class/TaskClientAsync#update) [![Apify API JavaScript Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/javascript.svg)](https://docs.apify.com/api/client/js/reference/class/TaskClient#update) Update settings of a task using values specified by an object passed as JSON in the POST payload. If the object does not define a specific property, its value is not updated. The response is the full task object as returned by the [Get task](#/reference/tasks/task-object/get-task) endpoint. The request needs to specify the `Content-Type: application/json` HTTP header! When providing your API authentication token, we recommend using the request's `Authorization` header, rather than the URL. ([More info](#/introduction/authentication) ). Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 **Response Headers** --- # Update task input | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Update task input ================= PUT /v2/actor-tasks/:actorTaskId/input ---------------------------------- Clients[![Apify API Python Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/python.svg)](https://docs.apify.com/api/client/python/reference/class/TaskClientAsync#update_input) [![Apify API JavaScript Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/javascript.svg)](https://docs.apify.com/api/client/js/reference/class/TaskClient#updateInput) Updates the input of a task using values specified by an object passed as JSON in the PUT payload. If the object does not define a specific property, its value is not updated. The response is the full task input as returned by the [Get task input](#/reference/tasks/task-input-object/get-task-input) endpoint. The request needs to specify the `Content-Type: application/json` HTTP header! When providing your API authentication token, we recommend using the request's `Authorization` header, rather than the URL. ([More info](#/introduction/authentication) ). Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 **Response Headers** --- # Get task input | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Get task input ============== GET /v2/actor-tasks/:actorTaskId/input ---------------------------------- Clients[![Apify API Python Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/python.svg)](https://docs.apify.com/api/client/python/reference/class/TaskClientAsync#get_input) [![Apify API JavaScript Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/javascript.svg)](https://docs.apify.com/api/client/js/reference/class/TaskClient#getInput) Returns the input of a given task. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 **Response Headers** --- # Get list of task runs | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Get list of task runs ===================== GET /v2/actor-tasks/:actorTaskId/runs --------------------------------- Get a list of runs of a specific task. The response is a list of objects, where each object contains essential information about a single task run. The endpoint supports pagination using the `limit` and `offset` parameters, and it does not return more than a 1000 array elements. By default, the records are sorted by the `startedAt` field in ascending order; therefore you can use pagination to incrementally fetch all records while new ones are still being created. To sort the records in descending order, use the `desc=1` parameter. You can also filter runs by status ([available statuses](https://docs.apify.com/platform/actors/running/runs-and-builds#lifecycle) ). Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 **Response Headers** --- # Get list of webhooks | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Get list of webhooks ==================== GET /v2/actor-tasks/:actorTaskId/webhooks ------------------------------------- Gets the list of webhooks of a specific Actor task. The response is a JSON with the list of objects, where each object contains basic information about a single webhook. The endpoint supports pagination using the `limit` and `offset` parameters and it will not return more than 1000 records. By default, the records are sorted by the `createdAt` field in ascending order, to sort the records in descending order, use the `desc=1` parameter. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 **Response Headers** --- # Run task | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Run task ======== POST /v2/actor-tasks/:actorTaskId/runs --------------------------------- Clients[![Apify API Python Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/python.svg)](https://docs.apify.com/api/client/python/reference/class/TaskClientAsync#call) [![Apify API JavaScript Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/javascript.svg)](https://docs.apify.com/api/client/js/reference/class/TaskClient#start) Runs an Actor task and immediately returns without waiting for the run to finish. Optionally, you can override the Actor input configuration by passing a JSON object as the POST payload and setting the `Content-Type: application/json` HTTP header. Note that if the object in the POST payload does not define a particular input property, the Actor run uses the default value defined by the task (or Actor's input schema if not defined by the task). The response is the Actor Run object as returned by the [Get run](#/reference/actor-runs/run-object-and-its-storages/get-run) endpoint. If you want to wait for the run to finish and receive the actual output of the Actor run as the response, use one of the [Run task synchronously](#/reference/actor-tasks/run-task-synchronously) API endpoints instead. To fetch the Actor run results that are typically stored in the default dataset, you'll need to pass the ID received in the `defaultDatasetId` field received in the response JSON to the [Get items](#/reference/datasets/item-collection/get-items) API endpoint. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 201 **Response Headers** **Location** --- # Run task synchronously | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Run task synchronously ====================== POST /v2/actor-tasks/:actorTaskId/run-sync ------------------------------------- Runs an Actor task and synchronously returns its output. The run must finish in 300 seconds otherwise the HTTP request fails with a timeout error (this won't abort the run itself). Optionally, you can override the Actor input configuration by passing a JSON object as the POST payload and setting the `Content-Type: application/json` HTTP header. Note that if the object in the POST payload does not define a particular input property, the Actor run uses the default value defined by the task (or Actor's input schema if not defined by the task). Beware that it might be impossible to maintain an idle HTTP connection for an extended period, due to client timeout or network conditions. Make sure your HTTP client is configured to have a long enough connection timeout. If the connection breaks, you will not receive any information about the run and its status. Input fields from Actor task configuration can be overloaded with values passed as the POST payload. Just make sure to specify `Content-Type` header to be `application/json` and input to be an object. To run the task asynchronously, use the [Run task](#/reference/actor-tasks/run-collection/run-task) API endpoint instead. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 201 * 400 **Response Headers** **Response Headers** --- # Run task synchronously | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Run task synchronously ====================== GET /v2/actor-tasks/:actorTaskId/run-sync ------------------------------------- Run a specific task and return its output. The run must finish in 300 seconds otherwise the HTTP request fails with a timeout error (this won't abort the run itself). Beware that it might be impossible to maintain an idle HTTP connection for an extended period, due to client timeout or network conditions. Make sure your HTTP client is configured to have a long enough connection timeout. If the connection breaks, you will not receive any information about the run and its status. To run the Task asynchronously, use the [Run task asynchronously](#/reference/actor-tasks/run-collection/run-task) endpoint instead. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 201 * 400 * 408 **Response Headers** **Response Headers** Request Timeout: the HTTP request exceeded the 300 second limit **Response Headers** --- # Run task synchronously and get dataset items | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Run task synchronously and get dataset items ============================================ POST /v2/actor-tasks/:actorTaskId/run-sync-get-dataset-items ------------------------------------------------------- Runs an Actor task and synchronously returns its dataset items. The run must finish in 300 seconds otherwise the HTTP request fails with a timeout error (this won't abort the run itself). Optionally, you can override the Actor input configuration by passing a JSON object as the POST payload and setting the `Content-Type: application/json` HTTP header. Note that if the object in the POST payload does not define a particular input property, the Actor run uses the default value defined by the task (or the Actor's input schema if not defined by the task). You can send all the same options in parameters as the [Get Dataset Items](#/reference/datasets/item-collection/get-items) API endpoint. Beware that it might be impossible to maintain an idle HTTP connection for an extended period, due to client timeout or network conditions. Make sure your HTTP client is configured to have a long enough connection timeout. If the connection breaks, you will not receive any information about the run and its status. Input fields from Actor task configuration can be overloaded with values passed as the POST payload. Just make sure to specify the `Content-Type` header as `application/json` and that the input is an object. To run the task asynchronously, use the [Run task](#/reference/actor-tasks/run-collection/run-task) API endpoint instead. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 201 * 400 **Response Headers** **X-Apify-Pagination-Offset** **X-Apify-Pagination-Limit** **X-Apify-Pagination-Count** **X-Apify-Pagination-Total** **Response Headers** --- # Run task synchronously and get dataset items | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Run task synchronously and get dataset items ============================================ GET /v2/actor-tasks/:actorTaskId/run-sync-get-dataset-items ------------------------------------------------------- Run a specific task and return its dataset items. The run must finish in 300 seconds otherwise the HTTP request fails with a timeout error (this won't abort the run itself). You can send all the same options in parameters as the [Get Dataset Items](#/reference/datasets/item-collection/get-items) API endpoint. Beware that it might be impossible to maintain an idle HTTP connection for an extended period, due to client timeout or network conditions. Make sure your HTTP client is configured to have a long enough connection timeout. If the connection breaks, you will not receive any information about the run and its status. To run the Task asynchronously, use the [Run task asynchronously](#/reference/actor-tasks/run-collection/run-task) endpoint instead. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 201 * 400 * 408 **Response Headers** **X-Apify-Pagination-Offset** **X-Apify-Pagination-Limit** **X-Apify-Pagination-Count** **X-Apify-Pagination-Total** **Response Headers** Request Timeout: the HTTP request exceeded the 300 second limit **Response Headers** --- # Get list of datasets | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Get list of datasets ==================== GET /v2/datasets ------------ Clients[![Apify API Python Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/python.svg)](https://docs.apify.com/api/client/python/reference/class/DatasetCollectionClientAsync#list) [![Apify API JavaScript Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/javascript.svg)](https://docs.apify.com/api/client/js/reference/class/DatasetCollectionClient#list) Lists all of a user's datasets. The response is a JSON array of objects, where each object contains basic information about one dataset. By default, the objects are sorted by the `createdAt` field in ascending order, therefore you can use pagination to incrementally fetch all datasets while new ones are still being created. To sort them in descending order, use `desc=1` parameter. The endpoint supports pagination using `limit` and `offset` parameters and it will not return more than 1000 array elements. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 **Response Headers** --- # Datasets - Introduction | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) This section describes API endpoints to manage Datasets. Dataset is a storage for structured data, where each record stored has the same attributes, such as online store products or real estate offers. You can imagine it as a table, where each object is a row and its attributes are columns. Dataset is an append-only storage - you can only add new records to it but you cannot modify or remove existing records. Typically it is used to store crawling results. For more information, see the [Datasets documentation](https://docs.apify.com/platform/storage/dataset) . note Some of the endpoints do not require the authentication token, the calls are authenticated using the hard-to-guess ID of the dataset. [Get list of datasets\ --------------------\ \ `/datasets`](/api/v2/datasets-get) [Create dataset\ --------------\ \ `/datasets`](/api/v2/datasets-post) [Get dataset\ -----------\ \ `/datasets/{datasetId}`](/api/v2/dataset-get) [Update dataset\ --------------\ \ `/datasets/{datasetId}`](/api/v2/dataset-put) [Delete dataset\ --------------\ \ `/datasets/{datasetId}`](/api/v2/dataset-delete) [Get items\ ---------\ \ `/datasets/{datasetId}/items`](/api/v2/dataset-items-get) [Store items\ -----------\ \ `/datasets/{datasetId}/items`](/api/v2/dataset-items-post) [Get dataset statistics\ ----------------------\ \ `/datasets/{datasetId}/statistics`](/api/v2/dataset-statistics-get) --- # Create dataset | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Create dataset ============== POST /v2/datasets ------------ Clients[![Apify API Python Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/python.svg)](https://docs.apify.com/api/client/python/reference/class/DatasetCollectionClientAsync#get_or_create) [![Apify API JavaScript Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/javascript.svg)](https://docs.apify.com/api/client/js/reference/class/DatasetCollectionClient#getOrCreate) Creates a dataset and returns its object. Keep in mind that data stored under unnamed dataset follows [data retention period](https://docs.apify.com/platform/storage#data-retention) . It creates a dataset with the given name if the parameter name is used. If a dataset with the given name already exists then returns its object. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 201 **Response Headers** **Location** --- # Get dataset | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Get dataset =========== GET /v2/datasets/:datasetId ----------------------- Clients[![Apify API Python Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/python.svg)](https://docs.apify.com/api/client/python/reference/class/DatasetClientAsync#get) [![Apify API JavaScript Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/javascript.svg)](https://docs.apify.com/api/client/js/reference/class/DatasetClient#get) Returns dataset object for given dataset ID. note Keep in mind that attributes `itemCount` and `cleanItemCount` are not propagated right away after data are pushed into a dataset. There is a short period (up to 5 seconds) during which these counters may not match with exact counts in dataset items. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 **Response Headers** --- # Update dataset | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Update dataset ============== PUT /v2/datasets/:datasetId ----------------------- Clients[![Apify API Python Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/python.svg)](https://docs.apify.com/api/client/python/reference/class/DatasetClientAsync#update) [![Apify API JavaScript Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/javascript.svg)](https://docs.apify.com/api/client/js/reference/class/DatasetClient#update) Updates a dataset's name using a value specified by a JSON object passed in the PUT payload. The response is the updated dataset object, as returned by the [Get dataset](#/reference/datasets/dataset-collection/get-dataset) API endpoint. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 **Response Headers** --- # Delete dataset | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Delete dataset ============== DELETE /v2/datasets/:datasetId ----------------------- Clients[![Apify API JavaScript Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/javascript.svg)](https://docs.apify.com/api/client/js/reference/class/DatasetClient#delete) Deletes a specific dataset. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 204 **Response Headers** --- # Key-value stores - Introduction | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) This section describes API endpoints to manage Key-value stores. Key-value store is a simple storage for saving and reading data records or files. Each data record is represented by a unique key and associated with a MIME content type. Key-value stores are ideal for saving screenshots, Actor inputs and outputs, web pages, PDFs or to persist the state of crawlers. For more information, see the [Key-value store documentation](https://docs.apify.com/platform/storage/key-value-store) . note Some of the endpoints do not require the authentication token, the calls are authenticated using a hard-to-guess ID of the key-value store. [Get list of key-value stores\ ----------------------------\ \ `/key-value-stores`](/api/v2/key-value-stores-get) [Create key-value store\ ----------------------\ \ `/key-value-stores`](/api/v2/key-value-stores-post) [Get store\ ---------\ \ `/key-value-stores/{storeId}`](/api/v2/key-value-store-get) [Update store\ ------------\ \ `/key-value-stores/{storeId}`](/api/v2/key-value-store-put) [Delete store\ ------------\ \ `/key-value-stores/{storeId}`](/api/v2/key-value-store-delete) [Get list of keys\ ----------------\ \ `/key-value-stores/{storeId}/keys`](/api/v2/key-value-store-keys-get) [Get record\ ----------\ \ `/key-value-stores/{storeId}/records/{recordKey}`](/api/v2/key-value-store-record-get) [Store record\ ------------\ \ `/key-value-stores/{storeId}/records/{recordKey}`](/api/v2/key-value-store-record-put) [Delete record\ -------------\ \ `/key-value-stores/{storeId}/records/{recordKey}`](/api/v2/key-value-store-record-delete) --- # Get list of key-value stores | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Get list of key-value stores ============================ GET /v2/key-value-stores -------------------- Clients[![Apify API Python Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/python.svg)](https://docs.apify.com/api/client/python/reference/class/KeyValueStoreCollectionClientAsync#list) [![Apify API JavaScript Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/javascript.svg)](https://docs.apify.com/api/client/js/reference/class/KeyValueStoreCollectionClient#list) Gets the list of key-value stores owned by the user. The response is a list of objects, where each objects contains a basic information about a single key-value store. The endpoint supports pagination using the `limit` and `offset` parameters and it will not return more than 1000 array elements. By default, the records are sorted by the `createdAt` field in ascending order, therefore you can use pagination to incrementally fetch all key-value stores while new ones are still being created. To sort the records in descending order, use the `desc=1` parameter. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 **Response Headers** --- # Get items | Apify Documentation [Skip to main content](#__docusaurus_skipToContent_fallback) Get items ========= GET /v2/datasets/:datasetId/items ----------------------------- Clients[![Apify API Python Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/python.svg)](https://docs.apify.com/api/client/python/reference/class/DatasetClientAsync#stream_items) [![Apify API JavaScript Client Reference](https://raw.githubusercontent.com/apify/openapi/b1206ac2adf8f39b05e5a09bf32c2802af58d851/assets/javascript.svg)](https://docs.apify.com/api/client/js/reference/class/DatasetClient#listItems) Returns data stored in the dataset in a desired format. ### Response format[​](#response-format "Direct link to Response format") The format of the response depends on `format` query parameter. The `format` parameter can have one of the following values: `json`, `jsonl`, `xml`, `html`, `csv`, `xlsx` and `rss`. The following table describes how each format is treated. | Format | Items | | --- | --- | | `json` | The response is a JSON, JSONL or XML array of raw item objects. | | `jsonl` | | `xml` | | `html` | The response is a HTML, CSV or XLSX table, where columns correspond to the properties of the item and rows correspond to each dataset item. | | `csv` | | `xlsx` | | `rss` | The response is a RSS file. Each item is displayed as child elements of one ``. | | Note that CSV, XLSX and HTML tables are limited to 2000 columns and the column names cannot be longer than 200 characters. JSON, XML and RSS formats do not have such restrictions. ### Hidden fields[​](#hidden-fields "Direct link to Hidden fields") The top-level fields starting with the `#` character are considered hidden. These are useful to store debugging information and can be omitted from the output by providing the `skipHidden=1` or `clean=1` query parameters. For example, if you store the following object to the dataset: { productName: "iPhone Xs", description: "Welcome to the big screens." #debug: { url: "https://www.apple.com/lae/iphone-xs/", crawledAt: "2019-01-21T16:06:03.683Z" }} The `#debug` field will be considered as hidden and can be omitted from the results. This is useful to provide nice cleaned data to end users, while keeping debugging info available if needed. The Dataset object returned by the API contains the number of such clean items in the`dataset.cleanItemCount` property. ### XML format extension[​](#xml-format-extension "Direct link to XML format extension") When exporting results to XML or RSS formats, the names of object properties become XML tags and the corresponding values become tag's children. For example, the following JavaScript object: { name: "Paul Newman", address: [ { type: "home", street: "21st", city: "Chicago" }, { type: "office", street: null, city: null } ]} will be transformed to the following XML snippet: Paul Newman
home 21st Chicago
office
If the JavaScript object contains a property named `@` then its sub-properties are exported as attributes of the parent XML element. If the parent XML element does not have any child elements then its value is taken from a JavaScript object property named `#`. For example, the following JavaScript object: { "address": [{ "@": { "type": "home" }, "street": "21st", "city": "Chicago" }, { "@": { "type": "office" }, "#": 'unknown' }]} will be transformed to the following XML snippet:
21st Chicago
unknown
This feature is also useful to customize your RSS feeds generated for various websites. By default the whole result is wrapped in a `` element and each page object is wrapped in a `` element. You can change this using `xmlRoot` and `xmlRow` url parameters. ### Pagination[​](#pagination "Direct link to Pagination") The generated response supports [pagination](#/introduction/pagination) . The pagination is always performed with the granularity of a single item, regardless whether `unwind` parameter was provided. By default, the **Items** in the response are sorted by the time they were stored to the database, therefore you can use pagination to incrementally fetch the items as they are being added. No limit exists to how many items can be returned in one response. If you specify `desc=1` query parameter, the results are returned in the reverse order than they were stored (i.e. from newest to oldest items). Note that only the order of **Items** is reversed, but not the order of the `unwind` array elements. Request[​](#request "Direct link to Request") ---------------------------------------------- Responses[​](#responses "Direct link to Responses") ---------------------------------------------------- * 200 **Response Headers** **X-Apify-Pagination-Offset** **X-Apify-Pagination-Limit** **X-Apify-Pagination-Count** **X-Apify-Pagination-Total** ---