Skip to main content

Apify API (1.0)

UPDATE 2024-07-09: We have rolled out this new Apify API Documentation. In case of any issues, please report here. The old API Documenatation is still available here.

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. There are two kinds of rate limits - a global rate limit and a per-resource rate limit.

Global rate limit

The global rate limit is set to 250 000 requests per minute. For authenticated requests, it is counted per user, and for unauthenticated requests, it is counted per IP address.

Per-resource rate limit

The default per-resource rate limit is 30 requests per second per resource, which in this context means a single Actor, a single Actor run, a single dataset, single key-value store etc. The default rate limit is applied to every API endpoint except a few select ones, which have higher rate limits. Each API endpoint returns its rate limit in X-RateLimit-Limit header. These endpoints have a rate limit of 100 requests per second per resource:

Rate limit exceeded errors

If the client is sending too many requests, the API endpoints respond with the HTTP status code 429 Too Many Requests and the following body:

{ "error": { "type": "rate-limit-exceeded", "message": "You have exceeded the rate limit of ... requests per second" } }

Retrying rate-limited requests with exponential backoff

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.

Actor collection

Get list of actors

ClientsApify API Python Client ReferenceApify API JavaScript Client ReferenceGets 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:
httpBearerapiKey
query Parameters
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 Schema: application/json
required
object (PaginationResponse)
total
required
number
offset
required
number
limit
required
number
desc
required
boolean
count
required
number
required
Array of objects (ActorShort)
Array
id
required
string
createdAt
required
string
modifiedAt
required
string
name
required
string
username
required
string

Response samples

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

Create actor

ClientsApify API Python Client ReferenceApify API JavaScript Client ReferenceCreates 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:
httpBearerapiKey
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 (Version)
Array
versionNumber
required
string
required
(any or null) or VersionSourceType (string)
buildTag
required
string
Array of objects or null (EnvVar)
applyEnvVarsToBuild
boolean 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)

categories
Array of strings or null
(any or null) or defaultRunOptions (object)
One of
any or null

Responses

Response Headers
Location
any
Response Schema: application/json
required
object (Actor)
id
required
string
userId
required
string
name
required
string
username
required
string
isPublic
required
boolean
createdAt
required
string
modifiedAt
required
string
required
object (ActorStats)
totalBuilds
required
number
totalRuns
required
number
totalUsers
required
number
totalUsers7Days
required
number
totalUsers30Days
required
number
totalUsers90Days
required
number
totalMetamorphs
required
number
lastRunStartedAt
required
string
required
Array of objects (Version)
Array
versionNumber
required
string
required
(any or null) or VersionSourceType (string)
buildTag
required
string
Array of objects or null (EnvVar)
applyEnvVarsToBuild
boolean 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)

required
object (defaultRunOptions)
build
required
string
timeoutSecs
required
number
memoryMbytes
required
number
deploymentKey
required
string
description
string or null
restartOnError
boolean or null
(any or null) or exampleRunInput (object)
One of
any or null
isDeprecated
boolean or null
title
string or null
(any or null) or taggedBuilds (object)
One of
any or null

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

Actor object

Get actor

ClientsApify API Python Client ReferenceApify API JavaScript Client ReferenceGets an object that contains all the details about a specific Actor.

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

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

Responses

Response Schema: application/json
required
object (Actor)
id
required
string
userId
required
string
name
required
string
username
required
string
isPublic
required
boolean
createdAt
required
string
modifiedAt
required
string
required
object (ActorStats)
totalBuilds
required
number
totalRuns
required
number
totalUsers
required
number
totalUsers7Days
required
number
totalUsers30Days
required
number
totalUsers90Days
required
number
totalMetamorphs
required
number
lastRunStartedAt
required
string
required
Array of objects (Version)
Array
versionNumber
required
string
required
(any or null) or VersionSourceType (string)
buildTag
required
string
Array of objects or null (EnvVar)
applyEnvVarsToBuild
boolean 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)

required
object (defaultRunOptions)
build
required
string
timeoutSecs
required
number
memoryMbytes
required
number
deploymentKey
required
string
description
string or null
restartOnError
boolean or null
(any or null) or exampleRunInput (object)
One of
any or null
isDeprecated
boolean or null
title
string or null
(any or null) or taggedBuilds (object)
One of
any or null

Response samples

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

Update actor

ClientsApify API Python Client ReferenceApify API JavaScript Client ReferenceUpdates 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:
httpBearerapiKey
path Parameters
actorId
required
string
Example: janedoe~my-actor

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

Request Body schema: application/json
required
name
required
string
isPublic
required
boolean
required
Array of objects (CreateOrUpdateEnvVarRequest)
Array
name
required
string
value
required
string
isSecret
boolean or null
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)
One of
any or null

Responses

Response Schema: application/json
required
object (Actor)
id
required
string
userId
required
string
name
required
string
username
required
string
isPublic
required
boolean
createdAt
required
string
modifiedAt
required
string
required
object (ActorStats)
totalBuilds
required
number
totalRuns
required
number
totalUsers
required
number
totalUsers7Days
required
number
totalUsers30Days
required
number
totalUsers90Days
required
number
totalMetamorphs
required
number
lastRunStartedAt
required
string
required
Array of objects (Version)
Array
versionNumber
required
string
required
(any or null) or VersionSourceType (string)
buildTag
required
string
Array of objects or null (EnvVar)
applyEnvVarsToBuild
boolean 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)

required
object (defaultRunOptions)
build
required
string
timeoutSecs
required
number
memoryMbytes
required
number
deploymentKey
required
string
description
string or null
restartOnError
boolean or null
(any or null) or exampleRunInput (object)
One of
any or null
isDeprecated
boolean or null
title
string or null
(any or null) or taggedBuilds (object)
One of
any or null

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

ClientsApify API JavaScript Client ReferenceDeletes an Actor.

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

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

Responses

Response Schema: application/json
object

Response samples

Content type
application/json
{ }

Version collection

Get list of versions

ClientsApify API Python Client ReferenceGets 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:
httpBearerapiKey
path Parameters
actorId
required
string
Example: janedoe~my-actor

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

Responses

Response Schema: application/json
required
object
total
required
number
required
Array of objects (Version)
Array
versionNumber
required
string
required
(any or null) or VersionSourceType (string)
buildTag
required
string
Array of objects or null (EnvVar)
applyEnvVarsToBuild
boolean 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)

Response samples

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

Create version

ClientsApify API Python Client ReferenceCreates 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:
httpBearerapiKey
path Parameters
actorId
required
string
Example: janedoe~my-actor

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

Request Body schema: application/json
required
versionNumber
string or null
(any or null) or VersionSourceType (string)
One of
any or null
Array of objects or null (EnvVar)
Array
name
required
string
value
required
string
isSecret
boolean or null
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

Response Headers
Location
any
Response Schema: application/json
required
object (Version)
versionNumber
required
string
required
(any or null) or VersionSourceType (string)
One of
any or null
buildTag
required
string
Array of objects or null (EnvVar)
Array
name
required
string
value
required
string
isSecret
boolean or null
applyEnvVarsToBuild
boolean 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)

Request samples

Content type
application/json
{}

Response samples

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

Version object

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.

Get version

ClientsApify API Python Client ReferenceThe 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:
httpBearerapiKey
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.

Responses

Response Schema: application/json
required
object (Version)
versionNumber
required
string
required
(any or null) or VersionSourceType (string)
One of
any or null
buildTag
required
string
Array of objects or null (EnvVar)
Array
name
required
string
value
required
string
isSecret
boolean or null
applyEnvVarsToBuild
boolean 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)

Response samples

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

Update version

ClientsApify API Python Client ReferenceThe 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:
httpBearerapiKey
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.

Request Body schema: application/json
required
versionNumber
string or null
(any or null) or VersionSourceType (string)
One of
any or null
Array of objects or null (EnvVar)
Array
name
required
string
value
required
string
isSecret
boolean or null
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

Response Schema: application/json
required
object (Version)
versionNumber
required
string
required
(any or null) or VersionSourceType (string)
One of
any or null
buildTag
required
string
Array of objects or null (EnvVar)
Array
name
required
string
value
required
string
isSecret
boolean or null
applyEnvVarsToBuild
boolean 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)

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

Responses

Response Schema: application/json
object

Response samples

Content type
application/json
{ }

Environment variable collection

Get list of environment variables

ClientsApify API Python Client ReferenceGets 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:
httpBearerapiKey
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

Responses

Response Schema: application/json
required
object
total
required
number
required
Array of objects (EnvVar)
Array
name
required
string
value
required
string
isSecret
boolean or null

Response samples

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

Create environment variable

ClientsApify API Python Client ReferenceCreates 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:
httpBearerapiKey
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

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

Responses

Response Headers
Location
any
Response Schema: application/json
required
object (EnvVar)
name
required
string
value
required
string
isSecret
boolean or null

Request samples

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

Response samples

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

Environment variable object

Get environment variable

ClientsApify API Python Client ReferenceGets 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:
httpBearerapiKey
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

Responses

Response Schema: application/json
required
object (EnvVar)
name
required
string
value
required
string
isSecret
boolean or null

Response samples

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

Update environment variable

ClientsApify API Python Client ReferenceUpdates 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:
httpBearerapiKey
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

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

Responses

Response Schema: application/json
required
object (EnvVar)
name
required
string
value
required
string
isSecret
boolean or null

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:
httpBearerapiKey
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

Responses

Response Schema: application/json
object

Response samples

Content type
application/json
{ }

Webhook collection

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:
httpBearerapiKey
path Parameters
actorId
required
string
Example: janedoe~my-actor

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

query Parameters
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 Schema: application/json
required
object (PaginationResponse)
total
required
number
offset
required
number
limit
required
number
desc
required
boolean
count
required
number
Array of objects (WebhookShort)
Array
id
required
string
createdAt
required
string
modifiedAt
required
string
userId
required
string
eventTypes
required
Array of strings
required
object (WebhookCondition)
ignoreSslErrors
required
boolean
doNotRetry
required
boolean
requestUrl
required
string
isAdHoc
boolean or null
shouldInterpolateStrings
boolean or null
object or null (ExampleWebhookDispatch)
object or null (WebhookStats)

Response samples

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

Build collection

Get list of builds

ClientsApify API Python Client ReferenceApify API JavaScript Client ReferenceGets 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:
httpBearerapiKey
path Parameters
actorId
required
string
Example: janedoe~my-actor

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

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

Responses

Response Schema: application/json
required
object
total
required
number
offset
required
number
limit
required
number
desc
required
boolean
count
required
number
required
Array of objects (BuildShort)
Array
id
required
string
status
required
string
startedAt
required
string
finishedAt
required
string
usageTotalUsd
required
number
actId
string
object (BuildsMeta)

Response samples

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

Build actor

ClientsApify API Python Client ReferenceApify API JavaScript Client ReferenceBuilds an Actor. The response is the build object as returned by the Get build endpoint.

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

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

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

Responses

Response Headers
Location
any
Response Schema: application/json
required
object (Build)
id
required
string
actId
required
string
userId
required
string
startedAt
required
string
status
required
string
required
object (BuildsMeta)
origin
required
string
clientIp
required
string
userAgent
required
string
buildNumber
required
string
finishedAt
string or null
(any or null) or BuildStats (object)
One of
any or null
(any or null) or BuildOptions (object)
One of
any or null
(any or null) or BuildUsage (object)
One of
any or null
usageTotalUsd
number or null
(any or null) or BuildUsage (object)
One of
any or null
inputSchema
string or null
readme
string or null

Response samples

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

Build object

[DEPRECATED] API endpoints related to build of the actor were moved under new namespace actor-builds.

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

Responses

Response Schema: application/json
required
object (Build)
id
required
string
actId
required
string
userId
required
string
startedAt
required
string
status
required
string
required
object (BuildsMeta)
origin
required
string
clientIp
required
string
userAgent
required
string
buildNumber
required
string
finishedAt
string or null
(any or null) or BuildStats (object)
One of
any or null
(any or null) or BuildOptions (object)
One of
any or null
(any or null) or BuildUsage (object)
One of
any or null
usageTotalUsd
number or null
(any or null) or BuildUsage (object)
One of
any or null
inputSchema
string or null
readme
string or null

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.

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

Responses

Response Schema: application/json
required
object (Build)
id
required
string
actId
required
string
userId
required
string
startedAt
required
string
status
required
string
required
object (BuildsMeta)
origin
required
string
clientIp
required
string
userAgent
required
string
buildNumber
required
string
finishedAt
string or null
(any or null) or BuildStats (object)
One of
any or null
(any or null) or BuildOptions (object)
One of
any or null
(any or null) or BuildUsage (object)
One of
any or null
usageTotalUsd
number or null
(any or null) or BuildUsage (object)
One of
any or null
inputSchema
string or null
readme
string or null

Response samples

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

Run collection

Get list of runs

ClientsApify API Python Client ReferenceApify API JavaScript Client ReferenceGets 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:
httpBearerapiKey
path Parameters
actorId
required
string
Example: janedoe~my-actor

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

query Parameters
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)

Responses

Response Schema: application/json
required
object (PaginationResponse)
total
required
number
offset
required
number
limit
required
number
desc
required
boolean
count
required
number
required
Array of objects (RunShort)
Array
id
required
string
actId
required
string
status
required
string
startedAt
required
string
finishedAt
required
string
buildId
required
string
buildNumber
required
string
required
object (RunMeta)
usageTotalUsd
required
number
defaultKeyValueStoreId
required
string
defaultDatasetId
required
string
defaultRequestQueueId
required
string
actorTaskId
string or null

Response samples

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

Run actor

ClientsApify API Python Client ReferenceApify API JavaScript Client ReferenceRuns 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:
httpBearerapiKey
path Parameters
actorId
required
string
Example: janedoe~my-actor

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

query Parameters
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 documentation.

Request Body schema: application/json
required
object

Responses

Response Headers
Location
any
Response Schema: application/json
required
object (Run)
id
required
string
actId
required
string
userId
required
string
startedAt
required
string
finishedAt
required
string
status
required
string
required
object (RunMeta)
origin
required
string
Enum: "DEVELOPMENT" "WEB" "API" "SCHEDULER" "TEST" "WEBHOOK" "ACTOR" "CLI" "STANDBY"
required
object (RunStats)
inputBodyLen
required
number
restartCount
required
number
resurrectCount
required
number
memAvgBytes
required
number
memMaxBytes
required
number
memCurrentBytes
required
number
cpuAvgUsage
required
number
cpuMaxUsage
required
number
cpuCurrentUsage
required
number
netRxBytes
required
number
netTxBytes
required
number
durationMillis
required
number
runTimeSecs
required
number
metamorph
required
number
computeUnits
required
number
required
object (RunOptions)
build
required
string
timeoutSecs
required
number
memoryMbytes
required
number
diskMbytes
required
number
buildId
required
string
defaultKeyValueStoreId
required
string
defaultDatasetId
required
string
defaultRequestQueueId
required
string
buildNumber
required
string
containerUrl
required
string
actorTaskId
string or null
statusMessage
string or null
isStatusMessageTerminal
boolean or null
exitCode
number or null
isContainerServerReady
boolean or null
gitBranchName
string or null
(any or null) or RunUsage (object)
One of
any or null
usageTotalUsd
number or null
(any or null) or RunUsage (object)
One of
any or null

Request samples

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

Response samples

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

Run actor synchronously

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:
httpBearerapiKey
path Parameters
actorId
required
string
Example: janedoe~my-actor

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

query Parameters
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
object

Responses

Response Schema: application/json
object
Response Schema: application/json
required
object
type
required
string
message
required
string
Response Schema: application/json
required
object
type
required
string
message
required
string

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:
httpBearerapiKey
path Parameters
actorId
required
string
Example: janedoe~my-actor

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

query Parameters
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 Schema: application/json
object
Response Schema: application/json
required
object
type
required
string
message
required
string
Response Schema: application/json
required
object
type
required
string
message
required
string

Response samples

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

Run Actor synchronously and get dataset items

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:
httpBearerapiKey
path Parameters
actorId
required
string
Example: janedoe~my-actor

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

query Parameters
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
object

Responses

Response Headers
X-Apify-Pagination-Offset
any
X-Apify-Pagination-Limit
any
X-Apify-Pagination-Count
any
X-Apify-Pagination-Total
any
Response Schema: application/json
object
Response Schema: application/json
required
object
type
required
string
message
required
string
Response Schema: application/json
required
object
type
required
string
message
required
string

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:
httpBearerapiKey
path Parameters
actorId
required
string
Example: janedoe~my-actor

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

query Parameters
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 Headers
X-Apify-Pagination-Offset
any
X-Apify-Pagination-Limit
any
X-Apify-Pagination-Count
any
X-Apify-Pagination-Total
any
Response Schema: application/json
object
Response Schema: application/json
required
object
type
required
string
message
required
string
Response Schema: application/json
required
object
type
required
string
message
required
string