Apify API

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.

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.

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.

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:

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:

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:

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:

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:

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:

• CRUD (get, put, delete) operations on key-value store records These endpoints have a rate limit of 200 requests per second per resource: * Run actor
• Run actor task asynchronously
• Run actor task synchronously
• Metamorph actor run
• Push items to dataset
• CRUD (add, get, update, delete) operations on requests in request queues

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
<span id="/introduction/rate-limiting/retrying-rate-limited-requests-with-exponential-backoff"></span>
If the client receives the rate limit error, it should wait a certain period of time and then retry the request. If the error happens again, the client should double the wait period and retry the request, and so on. This algorithm is known as _exponential backoff_ and it can be described using the following pseudo-code:
1. Define a variable `DELAY=500` 2. Send the HTTP request to the API endpoint 3. If the response has status code not equal to `429` then you are done. Otherwise:
   * Wait for a period of time chosen randomly from the interval `DELAY` to `2*DELAY` milliseconds
   * Double the future wait period by setting `DELAY = 2*DELAY`
   * Continue with step 2

If all requests sent by the client implement the above steps, the client will automatically use the maximum available bandwidth for its requests.
Note that the Apify API clients [for JavaScript](https://docs.apify.com/api/client/js) and [for Python](https://docs.apify.com/api/client/python) use the exponential backoff algorithm transparently, so that you do not need to worry about it.
## Referring to resources
<span id="/introduction/referring-to-resources"></span>
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.

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.

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:

For more information about source code and actor versions, see Source code in Actors documentation.