Skip to main content

Apify API (1.0)

The Apify API (version 2) provides programmatic access to the Apify platform. The API is organized around RESTful HTTP endpoints. All requests and responses (including errors) are encoded in JSON format with UTF-8 encoding, with a few exceptions that are explicitly described in the reference.

To access the API using Node.js, we recommend the apify-client NPM package. To access the API using Python, we recommend the apify-client PyPI package. 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

You can find your API token on the 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 <token>. E.g., Authorization: Bearer xxxxxxx. More info. (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 documentation.

Basic usage

To run an actor, send a POST request to the 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. This means you need to add your secret API token to the request's Authorization header (recommended) or as a URL query parameter ?token=[your_token] (less secure).

Optionally, you can include the query parameters described in the 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. It runs the actor using the account you are currently logged into (determined by the secret API token). The result is an actor run object and its output (if any).

A typical workflow is as follows:

  1. Run an actor or task using the Run actor or Run task API endpoints.

  2. Monitor the actor run by periodically polling its progress using the Get run API endpoint.

  3. Fetch the results from the 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 API endpoint using the defaultKeyValueStoreId and the store's key.

Note: Instead of periodic polling, you can also run your actor or task 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

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 or Key-value store 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 for more details.

Pagination

All API endpoints that return a list of records (e.g. 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, 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

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

The records in the 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 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

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

All API endpoints limit the rate of requests in order to prevent overloading of Apify servers by misbehaving clients. The default rate limit is 30 requests per second and is applied to every API endpoint except the following list of endpoints that are rate limited to 200 requests per second:

For authenticated API endpoints (if you use an authentication token), the limit is counted per user. Storage API endpoints (when a token isn't used) count the limit per store ID. Anonymous API endpoints count the limit per client IP adress. Each API endpoint returns its rate limit in X-RateLimit-Limit header.

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"
    }
}

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 and for Python use the exponential backoff algorithm transparently, so that you do not need to worry about it.

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.

Actors

The API endpoints described in this section enable you to manage, build and run Apify actors. For more information, see the Actor documentation.

Note that for all the API endpoints that accept the actorId parameter to specify an actor, you can pass either the actor ID (e.g. HG7ML7M8z78YcAPEB) or a tilde-separated username of the actor owner and the actor name (e.g. janedoe~my-actor).

Some of the API endpoints return runs objects. Note that 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.

Get list of Actors

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.

Authorizations:
httpBearer
query Parameters
token
required
string
Example: token=soSkq9ekdmfOslopH

API authentication token.

my
boolean
Example: my=true

If true or 1 then the returned list only contains Actors owned by the user. The default value is false.

offset
number <double>
Example: offset=10

Number of records that should be skipped at the start. The default value is 0.

limit
number <double>
Example: limit=99

Maximum number of records to return. The default value as well as the maximum is 1000.

desc
boolean
Example: desc=true

If true or 1 then the objects are sorted by the createdAt field in descending order. By default, they are sorted in ascending order.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Create Actor

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

If you want to make your Actor public 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.

Authorizations:
httpBearer
query Parameters
token
required
string
Example: token=soSkq9ekdmfOslopH

API authentication token.

offset
string
limit
string
desc
string
my
string
Request Body schema: application/json
required
name
string or null
description
string or null
title
string or null
isPublic
boolean or null
seoTitle
string or null
seoDescription
string or null
restartOnError
boolean or null
Array of objects or null (VersionUpdate)
categories
Array of strings or null
(any or null) or defaultRunOptions (object)

Responses

Request samples

Content type
application/json
{
  • "name": "MyActor",
  • "description": "My favourite Actor!",
  • "title": "My Actor",
  • "isPublic": false,
  • "seoTitle": "My Actor",
  • "seoDescription": "My Actor is the best",
  • "restartOnError": false,
  • "versions": [
    ],
  • "categories": [ ],
  • "defaultRunOptions": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get Actor

Gets an object that contains all the details about a specific Actor.

Authorizations:
httpBearer
path Parameters
actorId
required
string
Example: janedoe~my-actor

Actor ID or a tilde-separated owner's username and Actor name.

query Parameters
token
required
string
Example: token=soSkq9ekdmfOslopH

API authentication token.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update Actor

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

If you want to make your Actor public 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.

Authorizations:
httpBearer
path Parameters
actorId
required
string
Example: janedoe~my-actor

Actor ID or a tilde-separated owner's username and Actor name.

query Parameters
token
required
string
Example: token=soSkq9ekdmfOslopH

API authentication token.

Request Body schema: application/json
required
name
required
string
isPublic
required
boolean
required
Array of objects (VersionUpdate)
description
string or null
seoTitle
string or null
seoDescription
string or null
title
string or null
restartOnError
boolean or null
categories
Array of strings or null
(any or null) or defaultRunOptions (object)

Responses

Request samples

Content type
application/json
{
  • "name": "MyActor",
  • "description": "My favourite Actor!",
  • "isPublic": false,
  • "seoTitle": "My Actor",
  • "seoDescription": "My Actor is the best",
  • "title": "My Actor",
  • "restartOnError": false,
  • "versions": [
    ],
  • "categories": [ ],
  • "defaultRunOptions": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete Actor

Deletes an Actor.

Authorizations:
httpBearer
path Parameters
actorId
required
string
Example: janedoe~my-actor

Actor ID or a tilde-separated owner's username and Actor name.

query Parameters
token
required
string
Example: token=soSkq9ekdmfOslopH

API authentication token.

Responses

Response samples

Content type
application/json
{ }

Get list of versions

Gets the list of versions of a specific Actor. The response is a JSON object with the list of Version objects, where each contains basic information about a single version.

Authorizations:
httpBearer
path Parameters
actorId
required
string
Example: janedoe~my-actor

Actor ID or a tilde-separated owner's username and Actor name.

query Parameters
token
required
string
Example: token=soSkq9ekdmfOslopH

API authentication token.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Create version

Creates a version of an Actor using values specified in a 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 table below and in more detail in the Apify documentation.

For example, if an Actor's source code is stored in a GitHub 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 as returned by the Get version endpoint.

Authorizations:
httpBearer
path Parameters
actorId
required
string
Example: janedoe~my-actor

Actor ID or a tilde-separated owner's username and Actor name.

query Parameters
token
required
string
Example: token=soSkq9ekdmfOslopH

API authentication token.

Request Body schema: application/json
required
versionNumber
string or null
(any or null) or VersionSourceType (string)
Array of objects or null (envVars)
applyEnvVarsToBuild
boolean or null
buildTag
string or null
sourceFiles
Array of strings

-(object) - name: src/main.js (string, required) - format: TEXT (string, required) - content: console.log('This is the main.js file'); (string, required) -(object) - name: package.json (string, required) - format: TEXT (string, required) - content: name: "My Scraper" (string, required) -(object) - name: Dockerfile (string, required) - format: TEXT (string, required) - content: # Dockerfile contains instructions ... (string, required) -(object) - name: README.md (string, required) - format: TEXT (string, required) - content: My Actor scrapes the web (string, required)

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get version

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:

"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, see Source code in Actors documentation.Gets a Version object that contains all the details about a specific version of an Actor.

Authorizations:
httpBearer
path Parameters
actorId
required
string
Example: janedoe~my-actor

Actor ID or a tilde-separated owner's username and Actor name.

versionNumber
required
string
Example: 1.0

Actor major and minor version of the Actor.

query Parameters
token
required
string
Example: token=soSkq9ekdmfOslopH

API authentication token.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update version

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:

"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, see Source code in Actors documentation.Updates Actor version using values specified by a 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).

The response is the Version object as returned by the Get version endpoint.

Authorizations:
httpBearer
path Parameters
actorId
required
string
Example: janedoe~my-actor

Actor ID or a tilde-separated owner's username and Actor name.

versionNumber
required
string
Example: 1.0

Actor major and minor version of the Actor.

query Parameters
token
required
string
Example: token=soSkq9ekdmfOslopH

API authentication token.

Request Body schema: application/json
required
versionNumber
string or null
(any or null) or VersionSourceType (string)
Array of objects or null (envVars)
applyEnvVarsToBuild
boolean or null
buildTag
string or null
sourceFiles
Array of strings

-(object) - name: src/main.js (string, required) - format: TEXT (string, required) - content: console.log('This is the main.js file'); (string, required) -(object) - name: package.json (string, required) - format: TEXT (string, required) - content: name: "My Scraper" (string, required) -(object) - name: Dockerfile (string, required) - format: TEXT (string, required) - content: # Dockerfile contains instructions ... (string, required) -(object) - name: README.md (string, required) - format: TEXT (string, required) - content: My Actor scrapes the web (string, required)

Responses

Request samples

Content type
application/json
{
  • "versionNumber": "0.0",
  • "sourceType": "SOURCE_FILES",
  • "envVars": [
    ],
  • "applyEnvVarsToBuild": false,
  • "buildTag": "latest",
  • "sourceFiles": [ ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete version

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:

"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, see Source code in Actors documentation.Deletes a specific version of Actor's source code.

Authorizations:
httpBearer
path Parameters
actorId
required
string
Example: janedoe~my-actor

Actor ID or a tilde-separated owner's username and Actor name.

versionNumber
required
string
Example: 1.0

Actor major and minor version of the Actor.

query Parameters
token
required
string
Example: token=soSkq9ekdmfOslopH

API authentication token.

Responses

Response samples

Content type
application/json
{ }

Get list of environment variables

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, where each contains basic information about a single environment variable.

Authorizations:
httpBearer
path Parameters
actorId
required
string
Example: janedoe~my-actor

Actor ID or a tilde-separated owner's username and Actor name.

versionNumber
required
string
Example: 0.1

Actor version

query Parameters
token
required
string
Example: token=soSkq9ekdmfOslopH

API authentication token.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Create environment variable

Creates an environment variable of an Actor using values specified in a EnvVar 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 as returned by the Get environment variable endpoint.

Authorizations:
httpBearer
path Parameters
actorId
required
string
Example: janedoe~my-actor

Actor ID or a tilde-separated owner's username and Actor name.

versionNumber
required
string
Example: 0.1

Actor version

query Parameters
token
required
string
Example: token=soSkq9ekdmfOslopH

API authentication token.

Request Body schema: application/json
required
name
required
string
value
required
string
isSecret
boolean or null

Responses

Request samples

Content type
application/json
{
  • "name": "ENV_VAR_NAME",
  • "value": "my-env-var"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get environment variable

Gets a EnvVar 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.

Authorizations:
httpBearer
path Parameters
actorId
required
string
Example: janedoe~my-actor

Actor ID or a tilde-separated owner's username and Actor name.

versionNumber
required
string
Example: 0.1

Actor version

envVarName
required
string
Example: MY_ENV_VAR

The name of the environment variable

query Parameters
token
required
string
Example: token=soSkq9ekdmfOslopH

API authentication token.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update environment variable

Updates Actor environment variable using values specified by a EnvVar 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).

The response is the EnvVar object as returned by the Get environment variable endpoint.

Authorizations:
httpBearer
path Parameters
actorId
required
string
Example: janedoe~my-actor

Actor ID or a tilde-separated owner's username and Actor name.

versionNumber
required
string
Example: 0.1

Actor version

envVarName
required
string
Example: MY_ENV_VAR

The name of the environment variable

query Parameters
token
required
string
Example: token=soSkq9ekdmfOslopH

API authentication token.

Request Body schema: application/json
required
name
required
string
value
required
string
isSecret
boolean or null

Responses

Request samples

Content type
application/json
{
  • "name": "MY_ENV_VAR",
  • "value": "my-new-value",
  • "isSecret": false
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete environment variable

Deletes a specific environment variable.

Authorizations:
httpBearer
path Parameters
actorId
required
string
Example: janedoe~my-actor

Actor ID or a tilde-separated owner's username and Actor name.

versionNumber
required
string
Example: 0.1

Actor version

envVarName
required
string
Example: MY_ENV_VAR

The name of the environment variable

query Parameters
token
required
string
Example: token=soSkq9ekdmfOslopH

API authentication token.

Responses

Response samples

Content type
application/json
{ }

Get list of 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.

Authorizations:
httpBearer
path Parameters
actorId
required
string
Example: janedoe~my-actor

Actor ID or a tilde-separated owner's username and Actor name.

query Parameters
token
required
string
Example: token=soSkq9ekdmfOslopH

API authentication token.

offset
number <double>
Example: offset=10

Number of array elements that should be skipped at the start. The default value is 0.

limit
number <double>
Example: limit=99

Maximum number of array elements to return. The default value as well as the maximum is 1000.

desc
boolean
Example: desc=true

If true or 1 then the objects are sorted by the createdAt field in descending order. By default, they are sorted in ascending order.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get list of builds

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.

Authorizations:
httpBearer
path Parameters
actorId
required
string
Example: janedoe~my-actor

Actor ID or a tilde-separated owner's username and Actor name.

query Parameters
token
required
string
Example: token=soSkq9ekdmfOslopH

API authentication token.

offset
number <double>
Example: offset=10

Number of records that should be skipped at the start. The default value is 0.

limit
number <double>
Example: limit=99

Maximum number of records to return. The default value as well as the maximum is 1000.

desc
boolean
Example: desc=true

If true or 1 then the objects are sorted by the startedAt field in descending order. By default, they are sorted in ascending order.

waitForFinish
string
version
string
useCache
string
betaPackages
string
tag
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Build Actor

Builds an Actor. The response is the build object as returned by the Get build endpoint.

Authorizations:
httpBearer
path Parameters
actorId
required
string
Example: janedoe~my-actor

Actor ID or a tilde-separated owner's username and Actor name.

query Parameters
token
required
string
Example: token=soSkq9ekdmfOslopH

API authentication token.

version
required
string
Example: version=0.0

Actor version number to be built.

useCache
boolean
Example: useCache=true

If true or 1, the system will use a cache to speed up the build process. By default, cache is not used.

betaPackages
boolean
Example: betaPackages=true

If true or 1 then the Actor is built with beta versions of Apify NPM packages. By default, the build uses latest packages.

tag
string
Example: tag=latest

Tag to be applied to the build on success. By default, the tag is taken from Actor version's buildTag property.

waitForFinish
number <double>
Example: waitForFinish=60

The maximum number of seconds the server waits for the build to finish. By default it is 0, the maximum value is 60. If the build finishes in time then the returned build object will have a terminal status (e.g. SUCCEEDED), otherwise it will have a transitional status (e.g. RUNNING).

offset
string
limit
string
desc
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get build

[DEPRECATED] API endpoints related to build of the Actor were moved under new namespace 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. The calls are authenticated using a hard-to-guess ID of the build.

Authorizations:
httpBearer
path Parameters
actorId
required
string
Example: janedoe~my-actor

Actor ID or a tilde-separated owner's username and Actor name.

buildId
required
string
Example: soSkq9ekdmfOslopH

ID of the build you want to get, found in the build's Info tab.

query Parameters
waitForFinish
number <double>
Example: waitForFinish=60

The maximum number of seconds the server waits for the build to finish. By default it is 0, the maximum value is 60. If the build finishes in time then the returned build object will have a terminal status (e.g. SUCCEEDED), otherwise it will have a transitional status (e.g. RUNNING).

token
string
Example: token=soSkq9ekdmfOslopH

API authentication token. It is only required for private Actors. Builds of public Actors can be queried without any token.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Abort build

[DEPRECATED] API endpoints related to build of the Actor were moved under new namespace 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.

Authorizations:
httpBearer
path Parameters
actorId
required
string
Example: janedoe~my-actor

Actor ID or a tilde-separated owner's username and Actor name.

buildId
required
string
Example: 3KH8gEpp4d8uQSe8T

Build ID.

query Parameters
token
required
string
Example: token=soSkq9ekdmfOslopH

API authentication token.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get list of runs

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

Authorizations:
httpBearer
path Parameters
actorId
required
string
Example: janedoe~my-actor

Actor ID or a tilde-separated owner's username and Actor name.

query Parameters
token
required
string
Example: token=soSkq9ekdmfOslopH

API authentication token.

offset
number <double>
Example: offset=10

Number of array elements that should be skipped at the start. The default value is 0.

limit
number <double>
Example: limit=99

Maximum number of array elements to return. The default value as well as the maximum is 1000.

desc
boolean
Example: desc=true

If true or 1 then the objects are sorted by the startedAt field in descending order. By default, they are sorted in ascending order.

status
string
Example: status=SUCCEEDED

Return only runs with the provided status (available statuses)

waitForFinish
string
timeout
string
memory
string
build
string
webhooks
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Run Actor

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 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 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 API endpoint.

Authorizations:
httpBearer
path Parameters
actorId
required
string
Example: janedoe~my-actor

Actor ID or a tilde-separated owner's username and Actor name.

query Parameters
token
string
Example: token=soSkq9ekdmfOslopH

API authentication token. Public Actors that are configured to be anonymously runnable do not require the token.

timeout
number <double>
Example: timeout=60

Optional timeout for the run, in seconds. By default, the run uses a timeout specified in the default run configuration for the Actor.

memory
number <double>
Example: memory=256

Memory limit for the run, in megabytes. The amount of memory can be set to a power of 2 with a minimum of 128. By default, the run uses a memory limit specified in the default run configuration for the Actor.

maxItems
number <double>
Example: maxItems=1000

The maximum number of items that the Actor run should return. This is useful for pay-per-result Actors, as it allows you to limit the number of results that will be charged to your subscription. You can access the maximum number of items in your Actor by using the ACTOR_MAX_PAID_DATASET_ITEMS environment variable.

build
string
Example: build=0.1.234

Specifies the Actor build to run. It can be either a build tag or build number. By default, the run uses the build specified in the default run configuration for the Actor (typically latest).

waitForFinish
number <double>
Example: waitForFinish=60

The maximum number of seconds the server waits for the run to finish. By default, it is 0, the maximum value is 60. If the build finishes in time then the returned run object will have a terminal status (e.g. SUCCEEDED), otherwise it will have a transitional status (e.g. RUNNING).

webhooks
string
Example: webhooks=dGhpcyBpcyBqdXN0IGV4YW1wbGUK...

Specifies optional webhooks associated with the Actor run, which can be used to receive a notification e.g. when the Actor finished or failed. The value is a Base64-encoded JSON array of objects defining the webhooks. For more information, see Webhooks documenation.

offset
string
limit
string
desc
string
status
string
Request Body schema: application/json
required
foo
string

Responses

Request samples

Content type
application/json
{
  • "foo": "bar"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

With input

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 API endpoint instead.

Authorizations:
httpBearer
path Parameters
actorId
required
string
Example: janedoe~my-actor

Actor ID or a tilde-separated owner's username and Actor name.

query Parameters
token
string
Example: token=soSkq9ekdmfOslopH

API authentication token. Public Actors that are configured to be anonymously runnable do not require token parameter.

outputRecordKey
string
Example: outputRecordKey=OUTPUT

Key of the record from run's default key-value store to be returned in the response. By default, it is OUTPUT.

timeout
number <double>
Example: timeout=60

Optional timeout for the run, in seconds. By default, the run uses a timeout specified in the default run configuration for the Actor.

memory
number <double>
Example: memory=256

Memory limit for the run, in megabytes. The amount of memory can be set to a power of 2 with a minimum of 128. By default, the run uses a memory limit specified in the default run configuration for the Actor.

maxItems
number <double>
Example: maxItems=1000

The maximum number of items that the Actor run should return. This is useful for pay-per-result Actors, as it allows you to limit the number of results that will be charged to your subscription. You can access the maximum number of items in your Actor by using the ACTOR_MAX_PAID_DATASET_ITEMS environment variable.

build
string
Example: build=0.1.234

Specifies the Actor build to run. It can be either a build tag or build number. By default, the run uses the build specified in the default run configuration for the Actor (typically latest).

webhooks
string
Example: webhooks=dGhpcyBpcyBqdXN0IGV4YW1wbGUK...

Specifies optional webhooks associated with the Actor run, which can be used to receive a notification e.g. when the Actor finished or failed. The value is a Base64-encoded JSON array of objects defining the webhooks. For more information, see Webhooks documenation.

Request Body schema: application/json
required
foo
string

Responses

Request samples

Content type
application/json
{
  • "foo": "bar"
}

Response samples

Content type
application/json
{
  • "bar": "foo"
}

Without input

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 API endpoint instead.

Authorizations:
httpBearer
path Parameters
actorId
required
string
Example: janedoe~my-actor

Actor ID or a tilde-separated owner's username and Actor name.

query Parameters
token
string
Example: token=soSkq9ekdmfOslopH

API authentication token. Public Actors that are configured to be anonymously runnable do not require token parameter.

outputRecordKey
string
Example: outputRecordKey=OUTPUT

Key of the record from run's default key-value store to be returned in the response. By default, it is OUTPUT.

timeout
number <double>
Example: timeout=60

Optional timeout for the run, in seconds. By default, the run uses a timeout specified in the default run configuration for the Actor.

memory
number <double>
Example: memory=256

Memory limit for the run, in megabytes. The amount of memory can be set to a power of 2 with a minimum of 128. By default, the run uses a memory limit specified in the default run configuration for the Actor.

maxItems
number <double>
Example: maxItems=1000

The maximum number of items that the Actor run should return. This is useful for pay-per-result Actors, as it allows you to limit the number of results that will be charged to your subscription. You can access the maximum number of items in your Actor by using the ACTOR_MAX_PAID_DATASET_ITEMS environment variable.

build
string
Example: build=0.1.234

Specifies the Actor build to run. It can be either a build tag or build number. By default, the run uses the build specified in the default run configuration for the Actor (typically latest).

webhooks
string
Example: webhooks=dGhpcyBpcyBqdXN0IGV4YW1wbGUK...

Specifies optional webhooks associated with the Actor run, which can be used to receive a notification e.g. when the Actor finished or failed. The value is a Base64-encoded JSON array of objects defining the webhooks. For more information, see Webhooks documenation.

Responses

Response samples

Content type
application/json
{
  • "foo": "bar"
}

Run Actor synchronously with input and 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 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 API endpoint instead.

Authorizations:
httpBearer
path Parameters
actorId
required
string
Example: janedoe~my-actor

Actor ID or a tilde-separated owner's username and Actor name.

query Parameters
token
string
Example: token=soSkq9ekdmfOslopH

API authentication token. Public Actors that are configured to be anonymously runnable do not require token parameter.

timeout
number <double>
Example: timeout=60

Optional timeout for the run, in seconds. By default, the run uses a timeout specified in the default run configuration for the Actor.

memory
number <double>
Example: memory=256

Memory limit for the run, in megabytes. The amount of memory can be set to a power of 2 with a minimum of 128. By default, the run uses a memory limit specified in the default run configuration for the Actor.

maxItems
number <double>
Example: maxItems=1000

The maximum number of items that the Actor run should return. This is useful for pay-per-result Actors, as it allows you to limit the number of results that will be charged to your subscription. You can access the maximum number of items in your Actor by using the ACTOR_MAX_PAID_DATASET_ITEMS environment variable.

build
string
Example: build=0.1.234

Specifies the Actor build to run. It can be either a build tag or build number. By default, the run uses the build specified in the default run configuration for the Actor (typically latest).

webhooks
string
Example: webhooks=dGhpcyBpcyBqdXN0IGV4YW1wbGUK...

Specifies optional webhooks associated with the Actor run, which can be used to receive a notification e.g. when the Actor finished or failed. The value is a Base64-encoded JSON array of objects defining the webhooks. For more information, see Webhooks documenation.

format
string
Example: format=json

Format of the results, possible values are: json, jsonl, csv, html, xlsx, xml and rss. The default value is json.

clean
boolean
Example: clean=false

If true or 1 then the API endpoint returns only non-empty items and skips hidden fields (i.e. fields starting with the # character). The clean parameter is just a shortcut for skipHidden=true and skipEmpty=true parameters. Note that since some objects might be skipped from the output, that the result might contain less items than the limit value.

offset
number <double>
Example: offset=0

Number of items that should be skipped at the start. The default value is 0.

limit
number <double>
Example: limit=99

Maximum number of items to return. By default there is no limit.

fields
string
Example: fields=myValue,myOtherValue

A comma-separated list of fields which should be picked from the items, only these fields will remain in the resulting record objects. Note that the fields in the outputted items are sorted the same way as they are specified in the fields query parameter. You can use this feature to effectively fix the output format.

omit
string
Example: omit=myValue,myOtherValue

A comma-separated list of fields which should be omitted from the items.

unwind
string
Example: unwind=myValue

Name of a field which should be unwound. If the field is an array then every element of the array will become a separate record and merged with parent object. If the unwound field is an object then it is merged with the parent object If the unwound field is missing or its value is neither an array nor an object and therefore cannot be merged with a parent object then the item gets preserved as it is. Note that the unwound items ignore the desc parameter.

flatten
string
Example: flatten=myValue

A comma-separated list of fields which should transform nested objects into flat structures. For example, with flatten="foo" the object {"foo":{"bar": "hello"}} is turned into {"foo.bar": "hello"}. The original object with properties is replaced with the flattened object.

desc
boolean
Example: desc=true

By default, results are returned in the same order as they were stored. To reverse the order, set this parameter to true or 1.

attachment
boolean
Example: attachment=true

If true or 1 then the response will define the Content-Disposition: attachment header, forcing a web browser to download the file rather than to display it. By default this header is not present.

delimiter
string
Example: delimiter=;

A delimiter character for CSV files, only used if format=csv. You might need to URL-encode the character (e.g. use %09 for tab or %3B for semicolon). The default delimiter is a simple comma (,).

bom
boolean
Example: bom=false

All text responses are encoded in UTF-8 encoding. By default, the format=csv files are prefixed with the UTF-8 Byte Order Mark (BOM), while json, jsonl, xml, html and rss files are not. If you want to override this default behavior, specify bom=1 query parameter to include the BOM or bom=0 to skip it.

xmlRoot
string
Example: xmlRoot=items

Overrides default root element name of xml output. By default the root element is items.

xmlRow
string
Example: xmlRow=item

Overrides default element name that wraps each page or page function result object in xml output. By default the element name is item.

skipHeaderRow
boolean
Example: skipHeaderRow=true

If true or 1 then header row in the csv format is skipped.

skipHidden
boolean
Example: skipHidden=false

If true or 1 then hidden fields are skipped from the output, i.e. fields starting with the # character.

skipEmpty
boolean
Example: skipEmpty=false

If true or 1 then empty items are skipped from the output. Note that if used, the results might contain less items than the limit value.

simplified
boolean
Example: simplified=false

If true or 1 then, the endpoint applies the fields=url,pageFunctionResult,errorInfo and unwind=pageFunctionResult query parameters. This feature is used to emulate simplified results provided by the legacy Apify Crawler product and it's not recommended to use it in new integrations.

skipFailedPages
boolean
Example: skipFailedPages=false

If true or 1 then, the all the items with errorInfo property will be skipped from the output. This feature is here to emulate functionality of API version 1 used for the legacy Apify Crawler product and it's not recommended to use it in new integrations.

Request Body schema: application/json
required
foo
string

Responses

Request samples

Content type
application/json
{
  • "foo": "bar"
}

Response samples

Content type
application/json
[
  • {
    }
]

Run actor synchronously without input and 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 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 API endpoint instead.

Authorizations:
httpBearer
path Parameters
actorId
required
string
Example: janedoe~my-actor

Actor ID or a tilde-separated owner's username and Actor name.

query Parameters
token
string
Example: token=soSkq9ekdmfOslopH

API authentication token. Public Actors that are configured to be anonymously runnable do not require token parameter.

timeout
number <double>
Example: timeout=60

Optional timeout for the run, in seconds. By default, the run uses a timeout specified in the default run configuration for the Actor.

memory
number <double>
Example: memory=256

Memory limit for the run, in megabytes. The amount of memory can be set to a power of 2 with a minimum of 128. By default, the run uses a memory limit specified in the default run configuration for the Actor.

maxItems
number <double>
Example: maxItems=1000

The maximum number of items that the Actor run should return. This is useful for pay-per-result Actors, as it allows you to limit the number of results that will be charged to your subscription. You can access the maximum number of items in your Actor by using the ACTOR_MAX_PAID_DATASET_ITEMS environment variable.

build
string
Example: build=0.1.234

Specifies the Actor build to run. It can be either a build tag or build number. By default, the run uses the build specified in the default run configuration for the Actor (typically latest).

webhooks
string
Example: webhooks=dGhpcyBpcyBqdXN0IGV4YW1wbGUK...

Specifies optional webhooks associated with the Actor run, which can be used to receive a notification e.g. when the Actor finished or failed. The value is a Base64-encoded JSON array of objects defining the webhooks. For more information, see Webhooks documenation.

format
string
Example: format=json

Format of the results, possible values are: json, jsonl, csv, html, xlsx, xml and rss. The default value is json.

clean
boolean
Example: clean=false

If true or 1 then the API endpoint returns only non-empty items and skips hidden fields (i.e. fields starting with the # character). The clean parameter is just a shortcut for skipHidden=true and skipEmpty=true parameters. Note that since some objects might be skipped from the output, that the result might contain less items than the limit value.

offset
number <double>
Example: offset=0

Number of items that should be skipped at the start. The default value is 0.

limit
number <double>
Example: limit=99

Maximum number of items to return. By default there is no limit.

fields
string
Example: fields=myValue,myOtherValue

A comma-separated list of fields which should be picked from the items, only these fields will remain in the resulting record objects. Note that the fields in the outputted items are sorted the same way as they are specified in the fields query parameter. You can use this feature to effectively fix the output format.

omit
string
Example: omit=myValue,myOtherValue

A comma-separated list of fields which should be omitted from the items.

unwind
string
Example: unwind=myValue

Name of a field which should be unwound. If the field is an array then every element of the array will become a separate record and merged with parent object. If the unwound field is an object then it is merged with the parent object If the unwound field is missing or its value is neither an array nor an object and therefore cannot be merged with a parent object then the item gets preserved as it is. Note that the unwound items ignore the desc parameter.

flatten
string
Example: flatten=myValue

A comma-separated list of fields which should transform nested objects into flat structures. For example, with flatten="foo" the object {"foo":{"bar": "hello"}} is turned into {"foo.bar": "hello"}. The original object with properties is replaced with the flattened object.

desc
boolean
Example: desc=true

By default, results are returned in the same order as they were stored. To reverse the order, set this parameter to true or 1.

attachment
boolean
Example: attachment=true

If true or 1 then the response will define the Content-Disposition: attachment header, forcing a web browser to download the file rather than to display it. By default this header is not present.

delimiter
string
Example: delimiter=;

A delimiter character for CSV files, only used if format=csv. You might need to URL-encode the character (e.g. use %09 for tab or %3B for semicolon). The default delimiter is a simple comma (,).

bom
boolean
Example: bom=false

All text responses are encoded in UTF-8 encoding. By default, the format=csv files are prefixed with the UTF-8 Byte Order Mark (BOM), while json, jsonl, xml, html and rss files are not. If you want to override this default behavior, specify bom=1 query parameter to include the BOM or bom=0 to skip it.

xmlRoot
string
Example: xmlRoot=items

Overrides default root element name of xml output. By default the root element is items.

xmlRow
string
Example: xmlRow=item

Overrides default element name that wraps each page or page function result object in xml output. By default the element name is item.

skipHeaderRow
boolean
Example: skipHeaderRow=true

If true or 1 then header row in the csv format is skipped.

skipHidden
boolean
Example: skipHidden=false

If true or 1 then hidden fields are skipped from the output, i.e. fields starting with the # character.

skipEmpty
boolean
Example: skipEmpty=false

If true or 1 then empty items are skipped from the output. Note that if used, the results might contain less items than the limit value.

simplified
boolean
Example: simplified=false

If true or 1 then, the endpoint applies the fields=url,pageFunctionResult,errorInfo and unwind=pageFunctionResult query parameters. This feature is used to emulate simplified results provided by the legacy Apify Crawler product and it's not recommended to use it in new integrations.

skipFailedPages
boolean
Example: skipFailedPages=false

If true or 1 then, the all the items with errorInfo property will be skipped from the output. This feature is here to emulate functionality of API version 1 used for the legacy Apify Crawler product and it's not recommended to use it in new integrations.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get run

[DEPRECATED] API endpoints related to run of the Actor were moved under new namespace actor-runs.[DEPRECATED] API endpoints related to run of the Actor were moved under new namespace 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. The calls are authenticated using a hard-to-guess ID of the run.

Authorizations:
httpBearer
path Parameters
actorId
required
string
Example: janedoe~my-actor

Actor ID or a tilde-separated owner's username and Actor name.

runId
required
string
Example: 3KH8gEpp4d8uQSe8T

Run ID.

query Parameters
waitForFinish
number <double>
Example: waitForFinish=60

The maximum number of seconds the server waits for the run to finish. By default it is 0, the maximum value is 60. If the build finishes in time then the returned run object will have a terminal status (e.g. SUCCEEDED), otherwise it will have a transitional status (e.g. RUNNING).

token
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Abort run

[DEPRECATED] API endpoints related to run of the Actor were moved under new namespace 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.

Authorizations:
httpBearer
path Parameters
actorId
required
string
Example: janedoe~my-actor

Actor ID or a tilde-separated owner's username and Actor name.

runId
required
string
Example: 3KH8gEpp4d8uQSe8T

Run ID.

query Parameters
token
required
string
Example: token=soSkq9ekdmfOslopH

API authentication token.

gracefully
boolean
Example: gracefully=true

If true passed, the Actor run will abort gracefully. It will send aborting and persistState event into run and force-stop the run after 30 seconds. It is helpful in cases where you plan to resurrect the run later.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Metamorph run

[DEPRECATED] API endpoints related to run of the actor were moved under new namespace 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.

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.

Authorizations:
httpBearer
path Parameters
actorId
required
string
Example: janedoe~my-actor

Actor ID or a tilde-separated owner's username and Actor name.

runId
required
string
Example: 3KH8gEpp4d8uQSe8T

Actor run ID.

query Parameters
token
required
string
Example: token=soSkq9ekdmfOslopH

API authentication token.

targetActorId
required
string
Example: targetActorId=HDSasDasz78YcAPEB

ID of a target Actor that the run should be transformed into.

build
string
Example: build=beta

Optional build of the target Actor. It can be either a build tag or build number. By default, the run uses the build specified in the default run configuration for the target Actor (typically latest).

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Resurrect run

[DEPRECATED] API endpoints related to run of the Actor were moved under new namespace 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.

Authorizations:
httpBearer
path Parameters
actorId
required
string
Example: janedoe~my-actor

Actor ID or a tilde-separated owner's username and Actor name.

runId
required
string
Example: 3KH8gEpp4d8uQSe8T

Run ID.

query Parameters
token
required
string
Example: token=soSkq9ekdmfOslopH

API authentication token.

build
string
Example: build=0.1.234

Specifies the Actor build to run. It can be either a build tag or build number. By default, the run uses the build specified in the run that is being resurrected (typically latest).

timeout
number <double>
Example: timeout=60

Optional timeout for the run, in seconds. By default, the run uses a timeout specified in the run that is being resurrected.

memory
number <double>
Example: memory=256

Memory limit for the run, in megabytes. The amount of memory can be set to a power of 2 with a minimum of 128. By default, the run uses a memory limit specified in the run that is being resurrected.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get last run

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

Additionally, each of the above API endpoints supports all sub-endpoints of the original one:

Key-value store

  • /v2/acts/{actorId}/runs/last/key-value-store/keys{?token,status} Key collection

  • /v2/acts/{actorId}/runs/last/key-value-store/records/{recordKey}{?token,status} Record

Dataset

  • /v2/acts/{actorId}/runs/last/dataset/items{?token,status} Item collection

Request queue

  • /v2/acts/{actorId}/runs/last/request-queue/requests{?token,status} Request collection

  • /v2/acts/{actorId}/runs/last/request-queue/requests/{requestId}{?token,status} Request collection

  • /v2/acts/{actorId}/runs/last/request-queue/head{?token,status} 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.

Authorizations:
httpBearer
path Parameters
actorId
required
string
Example: janedoe~my-actor

Actor ID or a tilde-separated owner's username and Actor name.

query Parameters
token
required
string
Example: token=soSkq9ekdmfOslopH

API authentication token.

status
string
Example: status=SUCCEEDED

Filter for the run status.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Actor tasks

The API endpoints described in this section enable you to manage and run Apify actor tasks. For more information, see the Actor tasks documentation.

Note that 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 runs objects. Note that 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.

Get list of tasks

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.

Authorizations:
httpBearer
query Parameters
token
required
string
Example: token=soSkq9ekdmfOslopH

API authentication token.

offset
number <double>
Example: offset=10

Number of records that should be skipped at the start. The default value is 0.

limit
number <double>
Example: limit=99

Maximum number of records to return. The default value as well as the maximum is 1000.

desc
boolean
Example: desc=true

If true or 1 then the objects are sorted by the createdAt field in descending order. By default, they are sorted in ascending order.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Create task

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

Authorizations:
httpBearer
query Parameters
token
required
string
Example: token=soSkq9ekdmfOslopH

API authentication token.

offset
string
limit
string
desc
string
Request Body schema: application/json
required
actId
required
string
name
required
string
(any or null) or options (object)
(any or null) or input (object)

Responses

Request samples

Content type
application/json
{
  • "actId": "asADASadYvn4mBZmm",
  • "name": "my-task",
  • "options": {
    },
  • "input": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get task

Get an object that contains all the details about a task.

Authorizations:
httpBearer
path Parameters
actorTaskId
required
string
Example: janedoe~my-task

Task ID or a tilde-separated owner's username and task's name.

query Parameters
token
required
string
Example: token=soSkq9ekdmfOslopH

API authentication token.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update task

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

Authorizations:
httpBearer
path Parameters
actorTaskId
required
string
Example: janedoe~my-task

Task ID or a tilde-separated owner's username and task's name.

query Parameters
token
required
string
Example: token=soSkq9ekdmfOslopH

API authentication token.

Request Body schema: application/json
required
id
required
string
userId
required
string
actId
required
string
name
required
string
createdAt
required
string
modifiedAt
required
string
username
string or null
removedAt
string or null
(any or null) or stats1 (object)
(any or null) or options (object)
(any or null) or input (object)

Responses

Request samples

Content type
application/json
{
  • "id": "ZxLNxrRaZrSjuhT9y",
  • "userId": "BPWZBd7Z9c746JAnF",
  • "actId": "asADASadYvn4mBZmm",
  • "name": "my-task",
  • "username": "janedoe",
  • "createdAt": "2018-10-26T07:23:14.855Z",
  • "modifiedAt": "2018-10-26T13:30:49.578Z",
  • "removedAt": null,
  • "stats": {
    },
  • "options": {
    },
  • "input": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete task

Delete the task specified through the actorTaskId parameter.

Authorizations:
httpBearer
path Parameters
actorTaskId
required
string
Example: janedoe~my-task

Task ID or a tilde-separated owner's username and task's name.

query Parameters
token
required
string
Example: token=soSkq9ekdmfOslopH

API authentication token.

Responses

Response samples

Content type
application/json
{ }

Get task input

Returns the input of a given task.

Authorizations:
httpBearer
path Parameters
actorTaskId
required
string
Example: janedoe~my-task

Task ID or a tilde-separated owner's username and task's name.

query Parameters
token
required
string
Example: token=soSkq9ekdmfOslopH

API authentication token.

Responses

Response samples

Content type
application/json
{
  • "myField1": "some-value",
  • "myField2": "another-value",
  • "myField3": 1
}

Update task input

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

Authorizations:
httpBearer
path Parameters
actorTaskId
required
string
Example: janedoe~my-task

Task ID or a tilde-separated owner's username and task's name.

query Parameters
token
required
string
Example: token=soSkq9ekdmfOslopH

API authentication token.

Request Body schema: application/json
required
myField2
string or null

Responses

Request samples

Content type
application/json
{
  • "myField2": "updated-value"
}

Response samples

Content type
application/json
{
  • "myField1": "some-value",
  • "myField2": "updated-value",
  • "myField3": 1
}

Get list of 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.

Authorizations:
httpBearer
path Parameters
actorTaskId
required
string
Example: janedoe~my-task

Task ID or a tilde-separated owner's username and task's name.

query Parameters
token
required
string
Example: token=soSkq9ekdmfOslopH

API authentication token.

offset
number <double>
Example: offset=10

Number of array elements that should be skipped at the start. The default value is 0.

limit
number <double>
Example: limit=99

Maximum number of array elements to return. The default value as well as the maximum is 1000.

desc
boolean
Example: desc=true

If true or 1 then the objects are sorted by the createdAt field in descending order. By default, they are sorted in ascending order.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get list of task 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).

Authorizations:
httpBearer
path Parameters
actorTaskId
required
string
Example: janedoe~my-task

Task ID or a tilde-separated owner's username and task's name.

query Parameters
token
required
string
Example: token=soSkq9ekdmfOslopH

API authentication token.

offset
number <double>
Example: offset=10

Number of array elements that should be skipped at the start. The default value is 0.

limit
number <double>
Example: limit=99

Maximum number of array elements to return. The default value as well as the maximum is 1000.

desc
boolean
Example: desc=true

If true or 1 then the objects are sorted by the startedAt field in descending order. By default, they are sorted in ascending order.

status
string
Example: status=SUCCEEDED

Return only runs with the provided status (available statuses)

waitForFinish
string
webhooks
string
timeout
string
memory
string
build
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Run task

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 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 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 API endpoint.

Authorizations:
httpBearer
path Parameters
actorTaskId
required
string
Example: janedoe~my-task

Task ID or a tilde-separated owner's username and task's name.

query Parameters
token
string
Example: token=soSkq9ekdmfOslopH

API authentication token.

timeout
number <double>
Example: timeout=60

Optional timeout for the run, in seconds. By default, the run uses a timeout specified in the task settings.

memory
number <double>
Example: memory=256

Memory limit for the run, in megabytes. The amount of memory can be set to a power of 2 with a minimum of 128. By default, the run uses a memory limit specified in the task settings.

maxItems
number <double>
Example: maxItems=1000

The maximum number of items that the actor run should return. This is useful for pay-per-result actors, as it allows you to limit the number of results that will be charged to your subscription. You can access the maximum number of items in your actor by using the ACTOR_MAX_PAID_DATASET_ITEMS environment variable.

build
string
Example: build=0.1.234

Specifies the actor build to run. It can be either a build tag or build number. By default, the run uses the build specified in the task settings (typically latest).

waitForFinish
number <double>
Example: waitForFinish=60

The maximum number of seconds the server waits for the run to finish. By default, it is 0, the maximum value is 60. If the build finishes in time then the returned run object will have a terminal status (e.g. SUCCEEDED), otherwise it will have a transitional status (e.g. RUNNING).

webhooks
string
Example: webhooks=dGhpcyBpcyBqdXN0IGV4YW1wbGUK...

Specifies optional webhooks associated with the actor run, which can be used to receive a notification e.g. when the actor finished or failed. The value is a Base64-encoded JSON array of objects defining the webhooks. Note: if you already have a webhook set up for the actor or task, you do not have to add it again here. For more information, see Webhooks documenation.

offset
string
limit
string
desc
string
status
string
Request Body schema: application/json
required
foo
string

Responses

Request samples

Content type
application/json
{
  • "foo": "bar"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Run task synchronously (POST)

Runs an actor task and synchronously returns its output. The run must finish in 300 seconds otherwise the API endpoint returns a timeout error.

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 API endpoint instead.

Authorizations:
httpBearer
path Parameters
actorTaskId
required
string
Example: janedoe~my-task

Task ID or a tilde-separated owner's username and task's name.

query Parameters
token
string
Example: token=soSkq9ekdmfOslopH

API authentication token.

timeout
number <double>
Example: timeout=60

Optional timeout for the run, in seconds. By default, the run uses a timeout specified in the task settings.

memory
number <double>
Example: memory=256

Memory limit for the run, in megabytes. The amount of memory can be set to a power of 2 with a minimum of 128. By default, the run uses a memory limit specified in the task settings.

maxItems
number <double>
Example: maxItems=1000

The maximum number of items that the task run should return. This is useful for pay-per-result tasks, as it allows you to limit the number of results that will be charged to your subscription. You can access the maximum number of items in your actor by using the ACTOR_MAX_PAID_DATASET_ITEMS environment variable.

build
string
Example: build=0.1.234

Specifies the actor build to run. It can be either a build tag or build number. By default, the run uses the build specified in the task settings (typically latest).

outputRecordKey
string
Example: outputRecordKey=OUTPUT

Key of the record from run's default key-value store to be returned in the response. By default, it is OUTPUT.

webhooks
string
Example: webhooks=dGhpcyBpcyBqdXN0IGV4YW1wbGUK...

Specifies optional webhooks associated with the actor run, which can be used to receive a notification e.g. when the actor finished or failed. The value is a Base64-encoded JSON array of objects defining the webhooks. For more information, see Webhooks documenation.

Request Body schema: application/json
required
foo
string

Responses

Request samples

Content type
application/json
{
  • "foo": "bar"
}

Response samples

Content type
application/json
{
  • "bar": "foo"
}

Run task synchronously (GET)

Run a specific task and return its output. The run must finish in 300 seconds otherwise the API endpoint returns a timeout error.

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 endpoint instead.

Authorizations:
httpBearer
path Parameters
actorTaskId
required
string
Example: janedoe~my-task

Task ID or a tilde-separated owner's username and task's name.

query Parameters
token
string
Example: token=soSkq9ekdmfOslopH

API authentication token.

timeout
number <double>
Example: timeout=60

Optional timeout for the run, in seconds. By default, the run uses a timeout specified in the task settings.

memory
number <double>
Example: memory=256

Memory limit for the run, in megabytes. The amount of memory can be set to a power of 2 with a minimum of 128. By default, the run uses a memory limit specified in the task settings.

maxItems
number <double>
Example: maxItems=1000

The maximum number of items that the task run should return. This is useful for pay-per-result tasks, as it allows you to limit the number of results that will be charged to your subscription. You can access the maximum number of items in your actor by using the ACTOR_MAX_PAID_DATASET_ITEMS environment variable.

build
string
Example: build=0.1.234

Specifies the actor build to run. It can be either a build tag or build number. By default, the run uses the build specified in the task settings (typically latest).

outputRecordKey
string
Example: outputRecordKey=OUTPUT

Key of the record from run's default key-value store to be returned in the response. By default, it is OUTPUT.

webhooks
string
Example: webhooks=dGhpcyBpcyBqdXN0IGV4YW1wbGUK...

Specifies optional webhooks associated with the actor run, which can be used to receive a notification e.g. when the actor finished or failed. The value is a Base64-encoded JSON array of objects defining the webhooks. For more information, see Webhooks documenation.

Responses

Response samples

Content type
application/json
{
  • "bar": "foo"
}

Run task synchronously and get dataset items (POST)

Runs an actor task and synchronously returns its dataset items. The run must finish in 300 seconds otherwise the API endpoint returns a timeout error.

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 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 API endpoint instead.

Authorizations:
httpBearer
path Parameters
actorTaskId
required
string
Example: janedoe~my-task

Task ID or a tilde-separated owner's username and task's name.

query Parameters
token
string
Example: token=soSkq9ekdmfOslopH

API authentication token.

timeout
number <double>
Example: timeout=60

Optional timeout for the run, in seconds. By default, the run uses a timeout specified in the task settings.

memory
number <double>
Example: memory=256

Memory limit for the run, in megabytes. The amount of memory can be set to a power of 2 with a minimum of 128. By default, the run uses a memory limit specified in the task settings.

maxItems
number <double>
Example: maxItems=1000

The maximum number of items that the task run should return. This is useful for pay-per-result tasks, as it allows you to limit the number of results that will be charged to your subscription. You can access the maximum number of items in your actor by using the ACTOR_MAX_PAID_DATASET_ITEMS environment variable.

build
string
Example: build=0.1.234

Specifies the actor build to run. It can be either a build tag or build number. By default, the run uses the build specified in the task settings (typically latest).

webhooks
string
Example: webhooks=dGhpcyBpcyBqdXN0IGV4YW1wbGUK...

Specifies optional webhooks associated with the actor run, which can be used to receive a notification e.g. when the actor finished or failed. The value is a Base64-encoded JSON array of objects defining the webhooks. For more information, see Webhooks documenation.

format
string
Example: format=json

Format of the results, possible values are: json, jsonl, csv, html, xlsx, xml and rss. The default value is json.

clean
boolean
Example: clean=false

If true or 1 then the API endpoint returns only non-empty items and skips hidden fields (i.e. fields starting with the # character). The clean parameter is just a shortcut for skipHidden=true and skipEmpty=true parameters. Note that since some objects might be skipped from the output, that the result might contain less items than the limit value.

offset
number <double>
Example: offset=0

Number of items that should be skipped at the start. The default value is 0.

limit
number <double>
Example: limit=99

Maximum number of items to return. By default there is no limit.

fields
string
Example: fields=myValue,myOtherValue

A comma-separated list of fields which should be picked from the items, only these fields will remain in the resulting record objects. Note that the fields in the outputted items are sorted the same way as they are specified in the fields query parameter. You can use this feature to effectively fix the output format.

omit
string
Example: omit=myValue,myOtherValue

A comma-separated list of fields which should be omitted from the items.

unwind
string
Example: unwind=myValue

Name of a field which should be unwound. If the field is an array then every element of the array will become a separate record and merged with parent object. If the unwound field is an object then it is merged with the parent object If the unwound field is missing or its value is neither an array nor an object and therefore cannot be merged with a parent object then the item gets preserved as it is. Note that the unwound items ignore the desc parameter.

flatten
string
Example: