Apify API

Builds an Actor. The response is the build object as returned by the [Get build](#/reference/actors/build-object/get-build) endpoint.

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 dataset items](#/reference/datasets/item-collection/get-items) API endpoint.

Runs a specific Actor and returns a key-value store record. The POST payload including its `Content-Type` header is passed as `INPUT` to the Actor (usually <code>application/json</code>). The response contains the record stored under the `OUTPUT` key in the run's default key-value store. This is a legacy approach that has been replaced by the Actor [output object](https://docs.apify.com/platform/actors/development/actor-definition/output-schema#output-object-definition); Actors aren't required to store a record under this key, so the response may not contain any data. Use the `outputRecordKey` query parameter to return a different record. The Actor is started with the default options; you can override them using various URL query parameters. If the Actor run exceeds 300<!-- MAX_ACTOR_JOB_SYNC_WAIT_SECS --> 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.

Runs a specific Actor and returns its dataset items. The run must finish in 300<!-- MAX_ACTOR_JOB_SYNC_WAIT_SECS --> 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.

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<!-- MAX_ACTOR_JOB_SYNC_WAIT_SECS --> 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.

**[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).

Returns the default dataset associated with the last Actor run. This endpoint is a shortcut for getting the last run's `defaultDatasetId` and then using the [Get dataset](/api/v2/dataset-get) endpoint.

Returns data stored in the default dataset of the last Actor run in the desired format. This endpoint is a shortcut that resolves the last run's `defaultDatasetId` and proxies to the [Get dataset items](/api/v2/dataset-items-get) endpoint.

Returns statistics for the last Actor run's default dataset. This endpoint is a shortcut that resolves the last run's `defaultDatasetId` and proxies to the [Get dataset statistics](/api/v2/dataset-statistics-get) endpoint.

Gets an object that contains all the details about the default key-value store associated with the last Actor run. This endpoint is a shortcut for getting the run's `defaultKeyValueStoreId` and then using the [Get store](/api/v2/key-value-store-get) endpoint.

Returns a list of keys for the default key-value store of the last Actor run. This endpoint is a shortcut for getting the last run's `defaultKeyValueStoreId` and then using the [Get list of keys](/api/v2/key-value-store-keys-get) endpoint.

Gets a value stored under a specific key in the default key-value store of the last Actor run. This endpoint is a shortcut for getting the last run's `defaultKeyValueStoreId` and then using the [Get record](/api/v2/key-value-store-record-get) endpoint.

Returns the default request queue associated with the last Actor run. This endpoint is a shortcut for getting the last run's `defaultRequestQueueId` and then using the [Get request queue](/api/v2/request-queue-get) endpoint.

Returns a list of requests from the default request queue of the last Actor run. This endpoint is a shortcut for getting the last run's `defaultRequestQueueId` and then using the [List requests](/api/v2/request-queue-requests-get) endpoint.

Returns a request from the default request queue of the last Actor run. This endpoint is a shortcut for getting the last run's `defaultRequestQueueId` and then using the [Get request](/api/v2/request-queue-request-get) endpoint.

Returns the given number of first requests from the default request queue of the last Actor run. This endpoint is a shortcut for getting the last run's `defaultRequestQueueId` and then using the [Get head](/api/v2/request-queue-head-get) endpoint.

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 dataset items](#/reference/datasets/item-collection/get-items) API endpoint.

Runs an Actor task and synchronously returns a key-value store record. The response contains the record stored under the `OUTPUT` key in the run's default key-value store. This is a legacy approach that has been replaced by the Actor [output object](https://docs.apify.com/platform/actors/development/actor-definition/output-schema#output-object-definition); Actors aren't required to store a record under this key, so the response may not contain any data. Use the `outputRecordKey` query parameter to return a different record. The run must finish in 300<!-- MAX_ACTOR_JOB_SYNC_WAIT_SECS --> 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.

Run a specific task and return its dataset items. The run must finish in 300<!-- MAX_ACTOR_JOB_SYNC_WAIT_SECS --> 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.

Runs an Actor task and synchronously returns its dataset items. The run must finish in 300<!-- MAX_ACTOR_JOB_SYNC_WAIT_SECS --> 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.

Returns the default dataset associated with the last Actor task run. This endpoint is a shortcut for getting the last task run's `defaultDatasetId` and then using the [Get dataset](/api/v2/dataset-get) endpoint.

Returns data stored in the default dataset of the last Actor task run in the desired format. This endpoint is a shortcut that resolves the last task run's `defaultDatasetId` and proxies to the [Get dataset items](/api/v2/dataset-items-get) endpoint.

Returns statistics for the last Actor task run's default dataset. This endpoint is a shortcut that resolves the last task run's `defaultDatasetId` and proxies to the [Get dataset statistics](/api/v2/dataset-statistics-get) endpoint.

Gets an object that contains all the details about the default key-value store of the last Actor task run. This endpoint is a shortcut for getting the last task run's `defaultKeyValueStoreId` and then using the [Get store](/api/v2/key-value-store-get) endpoint.

Returns a list of keys for the default key-value store of the last Actor task run. This endpoint is a shortcut for getting the last task run's `defaultKeyValueStoreId` and then using the [Get list of keys](/api/v2/key-value-store-keys-get) endpoint.

Gets a value stored under a specific key in the default key-value store of the last Actor task run. This endpoint is a shortcut for getting the last task run's `defaultKeyValueStoreId` and then using the [Get record](/api/v2/key-value-store-record-get) endpoint.

Returns the default request queue associated with the last Actor task run. This endpoint is a shortcut for getting the last task run's `defaultRequestQueueId` and then using the [Get request queue](/api/v2/request-queue-get) endpoint.

Returns the given number of first requests from the default request queue of the last Actor task run. This endpoint is a shortcut for getting the last task run's `defaultRequestQueueId` and then using the [Get head](/api/v2/request-queue-head-get) endpoint.

Returns a list of requests from the default request queue of the last Actor task run. This endpoint is a shortcut for getting the last task run's `defaultRequestQueueId` and then using the [List requests](/api/v2/request-queue-requests-get) endpoint.

Returns a request from the default request queue of the last Actor task run. This endpoint is a shortcut for getting the last task run's `defaultRequestQueueId` and then using the [Get request](/api/v2/request-queue-request-get) endpoint.

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).

Returns the default dataset associated with an Actor run. This endpoint is a shortcut for getting the run's `defaultDatasetId` and then using the [Get dataset](/api/v2/dataset-get) endpoint.

Returns data stored in the default dataset of the Actor run in the desired format. This endpoint is a shortcut that resolves the run's `defaultDatasetId` and proxies to the [Get dataset items](/api/v2/dataset-items-get) endpoint.

Returns statistics for the Actor run's default dataset. This endpoint is a shortcut that resolves the run's `defaultDatasetId` and proxies to the [Get dataset statistics](/api/v2/dataset-statistics-get) endpoint.

Gets an object that contains all the details about the default key-value store. This endpoint is a shortcut for getting the run's `defaultKeyValueStoreId` and then using the [Get store](/api/v2/key-value-store-get) endpoint.

Returns a list of keys for the default key-value store of the Actor run. This endpoint is a shortcut for getting the run's `defaultKeyValueStoreId` and then using the [Get list of keys](/api/v2/key-value-store-keys-get) endpoint.

Gets a value stored under a specific key in the default key-value store of the Actor run. This endpoint is a shortcut for getting the run's `defaultKeyValueStoreId` and then using the [Get record](/api/v2/key-value-store-record-get) endpoint.

Returns the default request queue associated with an Actor run. This endpoint is a shortcut for getting the run's `defaultRequestQueueId` and then using the [Get request queue](/api/v2/request-queue-get) endpoint.

Returns a list of requests from the default request queue of the Actor run. This endpoint is a shortcut for getting the run's `defaultRequestQueueId` and then using the [List requests](/api/v2/request-queue-requests-get) endpoint.

Returns a request from the default request queue of the Actor run. This endpoint is a shortcut for getting the run's `defaultRequestQueueId` and then using the [Get request](/api/v2/request-queue-request-get) endpoint.

Returns the given number of first requests from the default request queue of the Actor run. This endpoint is a shortcut for getting the run's `defaultRequestQueueId` and then using the [Get head](/api/v2/request-queue-head-get) endpoint.

Gets an object that contains all the details about a specific key-value store.

Returns a list of objects describing keys of a given key-value store, as well as some information about the values (e.g. size). This endpoint is paginated using `exclusiveStartKey` and `limit` parameters - see [Pagination](/api/v2#using-key) for more details.

Gets a value stored in the key-value store under a specific key. The response body has the same `Content-Encoding` header as it was set in [Put record](#tag/Key-value-storesRecord/operation/keyValueStore_record_put). If the request does not define the `Accept-Encoding` HTTP header with the right encoding, the record will be decompressed. Most HTTP clients support decompression by default. After using the HTTP client with decompression support, the `Accept-Encoding` header is set by the client and body is decompressed automatically. Please note that for security reasons, Apify API can perform small modifications to HTML documents before they are served via this endpoint. To fetch the raw HTML content without any modifications, use the `attachment` query parameter.

Returns dataset object for given dataset ID. This does not return dataset items, only information about the storage itself. To retrieve dataset items, use the [List dataset items](/api/v2/dataset-items-get) endpoint. :::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.

Returns data stored in the dataset in a desired format. ### Response format The format of the response depends on <code>format</code> query parameter. The <code>format</code> parameter can have one of the following values: <code>json</code>, <code>jsonl</code>, <code>xml</code>, <code>html</code>, <code>csv</code>, <code>xlsx</code> and <code>rss</code>. The following table describes how each format is treated. <table> <tr> <th>Format</th> <th>Items</th> </tr> <tr> <td><code>json</code></td> <td rowspan="3">The response is a JSON, JSONL or XML array of raw item objects.</td> </tr> <tr> <td><code>jsonl</code></td> </tr> <tr> <td><code>xml</code></td> </tr> <tr> <td><code>html</code></td> <td rowspan="3">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.</td> </tr> <tr> <td><code>csv</code></td> </tr> <tr> <td><code>xlsx</code></td> </tr> <tr> <td><code>rss</code></td> <td colspan="2">The response is a RSS file. Each item is displayed as child elements of one <code>&lt;item&gt;</code>.</td> </tr> </table> 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 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 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: ``` <name>Paul Newman</name> <address> <type>home</type> <street>21st</street> <city>Chicago</city> </address> <address> <type>office</type> <street/> <city/> </address> ``` 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: ``` <address type="home"> <street>21st</street> <city>Chicago</city> </address> <address type="office">unknown</address> ``` This feature is also useful to customize your RSS feeds generated for various websites. By default the whole result is wrapped in a `<items>` element and each page object is wrapped in a `<item>` element. You can change this using <code>xmlRoot</code> and <code>xmlRow</code> url parameters. ### Pagination The generated response supports [pagination](#/introduction/pagination). The pagination is always performed with the granularity of a single item, regardless whether <code>unwind</code> 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.

Returns statistics for given dataset. Provides only [field statistics](https://docs.apify.com/platform/actors/development/actor-definition/dataset-schema/validation#dataset-field-statistics).

Returns queue object for given queue ID.

Returns a list of requests. This endpoint is paginated using cursor (pagination by `exclusiveStartId` is deprecated) and limit parameters.

Returns request from queue.

Returns given number of first requests from the queue. The response contains the `hadMultipleClients` boolean field which indicates that the queue was accessed by more than one client (with unique or empty `clientKey`). This field is used by [Apify SDK](https://sdk.apify.com) to determine whether the local cache is consistent with the request queue, and thus optimize performance of certain operations.