Skip to content
Merged
Show file tree
Hide file tree
Changes from 4 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -125,7 +125,7 @@ solution = add_all_numbers(actor_input)
print(solution)
```

> For a better understanding of the API endpoints for reading and modifying key-value stores, check the [official API reference](/api/v2#/reference/key-value-stores).
> For a better understanding of the API endpoints for reading and modifying key-value stores, check the [official API reference](/api/v2/storage-key-value-stores).

## Writing output {#writing-output}

Expand Down
6 changes: 3 additions & 3 deletions sources/academy/platform/getting_started/apify_api.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ slug: /getting-started/apify-api

---

[Apify's API](/api/v2#/reference) is your ticket to the Apify platform without even needing to access the [Apify Console](https://console.apify.com?asrc=developers_portal) web-interface. The API is organized around RESTful HTTP endpoints.
[Apify's API](/api/v2) web-interface. The API is organized around RESTful HTTP endpoints.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It seems there was an editing mistake here - removing up to the wrong parenthesis.


In this lesson, we'll be learning how to use the Apify API to call an Actor and view its results. We'll be using the Actor we created in the previous lesson, so if you haven't already gotten that one set up, go ahead do that before moving forward if you'd like to follow along.

Expand Down Expand Up @@ -45,7 +45,7 @@ Let's say we want to run our **adding-actor** via API and view its results in CS
https://api.apify.com/v2/acts/YOUR_USERNAME~adding-actor/run-sync-get-dataset-items?token=YOUR_TOKEN_HERE&format=csv
```

Additional parameters can be passed to this endpoint. You can learn about them [here](/api/v2#/reference/actors/run-actor-synchronously-and-get-dataset-items/run-actor-synchronously-with-input-and-get-dataset-items)
Additional parameters can be passed to this endpoint. You can learn about them in our [API documentation](/api/v2/act-run-sync-get-dataset-items-post)

> Network components can record visited URLs, so it's more secure to send the token as a HTTP header, not as a parameter. The header should look like `Authorization: Bearer YOUR_TOKEN`. Popular HTTP clients, such as [Postman](../../glossary/tools/postman.md) or [Insomnia](../../glossary/tools/insomnia.md), provide a convenient way to configure the Authorization header for all your API requests.

Expand All @@ -65,7 +65,7 @@ And there it is! The Actor was run with our inputs of **num1** and **num2**, the

## Apify API's many features {#api-many-features}

What we've done in this lesson only scratches the surface of what the Apify API can do. Right from Insomnia, or from any HTTP client, you can [manage datasets](/api/v2#/reference/datasets/dataset/get-dataset) and [key-value stores](/api/v2#/reference/key-value-stores/key-collection/get-dataset), [add to request queues](/api/v2#/reference/request-queues/queue-collection/add-request), [update Actors](/api/v2#/reference/actors/actor-object/add-request), and much more! Basically, whatever you can do on the platform's web interface, you also do through the API.
What we've done in this lesson only scratches the surface of what the Apify API can do. Right from Insomnia, or from any HTTP client, you can [manage datasets](/api/v2/storage-datasets) and [key-value stores](/api/v2/storage-key-value-stores), [add to request queues]/api/v2/storage-request-queues), [update Actors](/api/v2/storage-request-queues-requests), and much more! Basically, whatever you can do on the platform's web interface, you also do through the API.

## Next up {#next}

Expand Down
4 changes: 2 additions & 2 deletions sources/academy/platform/getting_started/apify_client.md
Original file line number Diff line number Diff line change
Expand Up @@ -114,7 +114,7 @@ run = client.actor('YOUR_USERNAME/adding-actor').call(run_input={
</TabItem>
</Tabs>

> Learn more about the `.call()` function [here](/api/client/js/reference/class/ApifyClient#actor).
> Learn more about the `.call()` function in our [API documentation](/api/client/js/reference/class/ApifyClient#actor).

## Downloading dataset items {#downloading-dataset-items}

Expand Down Expand Up @@ -220,7 +220,7 @@ print(items)

If you check the **Settings** tab within your **adding-actor**, you'll notice that the default memory being allocated to the Actor is **2048 MB**. This is a bit overkill considering the fact that the Actor is only adding two numbers together - **256 MB** would be much more reasonable. Also, we can safely say that the run should never take more than 20 seconds (even this is a generous number) and that the default of 3600 seconds is also overkill.

Let's change these two Actor settings via the Apify client using the [`actor.update()`](/api/client/js/reference/class/ActorClient#update) function. This function will call the **update Actor** endpoint, which can take `defaultRunOptions` as an input property. You can find the shape of the `defaultRunOptions` in the [API documentation](/api/v2#/reference/actors/actor-object/update-actor). Perfect!
Let's change these two Actor settings via the Apify client using the [`actor.update()`](/api/client/js/reference/class/ActorClient#update) function. This function will call the **update Actor** endpoint, which can take `defaultRunOptions` as an input property. You can find the shape of the `defaultRunOptions` in the [API documentation](/api/v2/act-put). Perfect!

First, we'll create a pointer to our Actor, similar to before (except this time, we won't be using `.call()` at the end):

Expand Down
4 changes: 2 additions & 2 deletions sources/academy/platform/running_a_web_server.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ Sometimes, an Actor needs a channel for communication with other systems (or hum
- An API to receive commands.
- An HTML page displaying output data.

Running a web server in an Actor is a piece of cake! Each Actor run is available at a unique URL (container URL) which always takes the form `https://CONTAINER-KEY.runs.apify.net`. This URL is available in the [**Actor run** object](/api/v2#/reference/actor-runs/run-object-and-its-storages/get-run) returned by the Apify API, as well as in the Apify console.
Running a web server in an Actor is a piece of cake! Each Actor run is available at a unique URL (container URL) which always takes the form `https://CONTAINER-KEY.runs.apify.net`. This URL is available in the [**Actor run** object](/api/v2/actor-run-get) returned by the Apify API, as well as in the Apify console.

If you start a web server on the port defined by the **APIFY_CONTAINER_PORT** environment variable (the default value is **4321**), the container URL becomes available and gets displayed in the **Live View** tab in the Actor run console.

Expand Down Expand Up @@ -236,4 +236,4 @@ When we deploy and run this Actor on the Apify platform, then we can open the **

With that, we're done! And our application works like a charm :)

The complete code of this Actor is available [here](https://apify.com/apify/example-web-server). You can run it there or copy it to your account.
The complete code of this Actor is available at it's [page](https://apify.com/apify/example-web-server). You can run it there or copy it to your account.
Copy link
Contributor

@tomnosek tomnosek Jul 16, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It should be "on its", not "at it's". But also, saying "on its page" with a basic link is lazy writing 😄 Why not to say "on its Apify Store page" and link it directly to https://apify.com/apify/example-web-server/source-code?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That is what I get for making last minute fixes late at night , good catch will address it

Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ If the Actor being run via API takes 5 minutes or less to complete a typical run

> If you are unsure about the differences between an Actor and a task, you can read about them in the [tasks](/platform/actors/running/tasks) documentation. In brief, tasks are pre-configured inputs for Actors.

The API endpoints and usage (for both sync and async) for [Actors](/api/v2#tag/ActorsRun-collection/operation/act_runs_post) and [tasks](/api/v2#/reference/actor-tasks/run-collection/run-task) are essentially the same.
The API endpoints and usage (for both sync and async) for [Actors](/api/v2#tag/ActorsRun-collection/operation/act_runs_post) and [tasks](/api/v2/actor-task-runs-post) are essentially the same.

To run, or **call**, an Actor/task, you will need a few things:

Expand Down Expand Up @@ -86,7 +86,7 @@ If we press **Send**, it will immediately return some info about the run. The `s

![Actor run info in Postman](./images/run-info-postman.png)

We will later use this **run info** JSON to retrieve the run's output data. This info about the run can also be retrieved with another call to the [**Get run**](https://apify.com/docs/api/v2#/reference/actors/run-object/get-run) endpoint.
We will later use this **run info** JSON to retrieve the run's output data. This info about the run can also be retrieved with another call to the [**Get run**](/api/v2/act-run-get) endpoint.

## JavaScript and Python client {#javascript-and-python-client}

Expand Down Expand Up @@ -150,7 +150,7 @@ If your synchronous run exceeds the 5-minute time limit, the response will be a

### Synchronous runs with dataset output {#synchronous-runs-with-dataset-output}

Most Actor runs will store their data in the default [dataset](/platform/storage/dataset). The Apify API provides **run-sync-get-dataset-items** endpoints for [Actors](/api/v2#/reference/actors/run-actor-synchronously-and-get-dataset-items/run-actor-synchronously-with-input-and-get-dataset-items) and [tasks](/api/v2#/reference/actor-tasks/run-task-synchronously-and-get-dataset-items/run-task-synchronously-and-get-dataset-items-(post)), which allow you to run an Actor and receive the items from the default dataset once the run has finished.
Most Actor runs will store their data in the default [dataset](/platform/storage/dataset). The Apify API provides **run-sync-get-dataset-items** endpoints for [Actors](/api/v2/act-run-sync-get-dataset-items-post) and [tasks](/api/v2/actor-task-run-sync-get-dataset-items-post), which allow you to run an Actor and receive the items from the default dataset once the run has finished.

Here is a Node.js example of calling a task via the API and logging the dataset items to the console:

Expand Down Expand Up @@ -187,9 +187,7 @@ items.forEach((item) => {

### Synchronous runs with key-value store output {#synchronous-runs-with-key-value-store-output}

[Key-value stores](/platform/storage/key-value-store) are useful for storing files like images, HTML snapshots, or JSON data. The Apify API provides **run-sync** endpoints for [Actors](/api/v2#/reference/actors/run-actor-synchronously/with-input) and [tasks](/api/v2#/reference/actor-tasks/run-task-synchronously/run-task-synchronously), which allow you to run a specific task and receive the output. By default, they return the `OUTPUT` record from the default key-value store.

> For more detailed information, check the [API reference](/api/v2#/reference/actors/run-actor-synchronously-and-get-dataset-items/run-actor-synchronously-with-input-and-get-dataset-items).
[Key-value stores](/platform/storage/key-value-store) are useful for storing files like images, HTML snapshots, or JSON data. The Apify API provides **run-sync** endpoints for [Actors](/api/v2/act-run-sync-post) and [tasks](/api/v2/actor-task-run-sync-post), which allow you to run a specific task and receive the output. By default, they return the `OUTPUT` record from the default key-value store.

## Asynchronous flow {#asynchronous-flow}

Expand All @@ -215,7 +213,7 @@ This solution is quite similar to the synchronous flow. To make the POST request
https://api.apify.com/v2/acts/apify~web-scraper/runs?token=YOUR_TOKEN&waitForFinish=60
```

You can also use the `waitForFinish` parameter with the [**GET Run** endpoint](/api/v2#/reference/actors/run-object/get-run) to implement a smarter [polling](#polling) system.
You can also use the `waitForFinish` parameter with the [**GET Run** endpoint](/api/v2/actor-run-get) to implement a smarter [polling](#polling) system.

Once again, the final response will be the **run info object**; however, now its status should be `SUCCEEDED` or `FAILED`. If the run exceeds the `waitForFinish` duration, the status will still be `RUNNING`.

Expand All @@ -237,7 +235,7 @@ Once your server receives this request from the webhook, you know that the event

What if you don't have a server, and the run you'd like to do is much too long to use a synchronous call? In cases like these, periodic **polling** of the run's status is the solution.

When we run the Actor with the [usual API call](#run-an-actor-or-task) shown above, we will back a response with the **run info** object. From this JSON object, we can then extract the ID of the Actor run that we just started from the `id` field. Then, we can set an interval that will poll the Apify API (let's say every 5 seconds) by calling the [**Get run**](https://apify.com/docs/api/v2#/reference/actors/run-object/get-run) endpoint to retrieve the run's status.
When we run the Actor with the [usual API call](#run-an-actor-or-task) shown above, we will back a response with the **run info** object. From this JSON object, we can then extract the ID of the Actor run that we just started from the `id` field. Then, we can set an interval that will poll the Apify API (let's say every 5 seconds) by calling the [**Get run**](/api/v2/actor-run-get) endpoint to retrieve the run's status.

Replace the `RUN_ID` in the following URL with the ID you extracted earlier:

Expand All @@ -257,15 +255,15 @@ The **run info** JSON also contains the IDs of the default [dataset](/platform/s

> If you are scraping products, or any list of items with similar fields, the [dataset](/platform/storage/dataset) should be your storage of choice. Don't forget though, that dataset items are immutable. This means that you can only add to the dataset, and not change the content that is already inside it.

To retrieve the data from a dataset, send a GET request to the [**Get items**](/api/v2#/reference/datasets/item-collection/get-items) endpoint and pass the `defaultDatasetId` into the URL. For a GET request to the default dataset, no token is needed.
To retrieve the data from a dataset, send a GET request to the [**Get items**](/api/v2/dataset-items-get) endpoint and pass the `defaultDatasetId` into the URL. For a GET request to the default dataset, no token is needed.

```cURL
https://api.apify.com/v2/datasets/DATASET_ID/items
```

By default, it will return the data in JSON format with some metadata. The actual data are in the `items` array.

You can use plenty of additional parameters, to learn more about them, visit our API reference [documentation](/api/v2#/reference/datasets/item-collection/get-items). We will only mention that you can pass a `format` parameter that transforms the response into popular formats like CSV, XML, Excel, RSS, etc.
You can use plenty of additional parameters, to learn more about them, visit our API reference [documentation](/api/v2/dataset-items-get). We will only mention that you can pass a `format` parameter that transforms the response into popular formats like CSV, XML, Excel, RSS, etc.

The items are paginated, which means you can ask only for a subset of the data. Specify this using the `limit` and `offset` parameters. This endpoint has a limit of 250,000 items that it can return per request. To retrieve more, you will need to send more requests incrementing the `offset` parameter.

Expand All @@ -279,13 +277,13 @@ https://api.apify.com/v2/datasets/DATASET_ID/items?format=csv&offset=250000

When you want to retrieve something from a key-value store, the `defaultKeyValueStoreId` is _not_ enough. You also need to know the name (or **key**) of the record you want to retrieve.

If you have a single output JSON, the convention is to return it as a record named `OUTPUT` to the default key-value store. To retrieve the record's content, call the [**Get record**](/api/v2#/reference/key-value-stores/record/get-record) endpoint.
If you have a single output JSON, the convention is to return it as a record named `OUTPUT` to the default key-value store. To retrieve the record's content, call the [**Get record**](/api/v2/key-value-store-record-get) endpoint.

```cURL
https://api.apify.com/v2/key-value-stores/STORE_ID/records/RECORD_KEY
```

If you don't know the keys (names) of the records in advance, you can retrieve just the keys with the [**List keys**](https://apify.com/docs/api/v2#/reference/key-value-stores/key-collection/get-list-of-keys) endpoint.
If you don't know the keys (names) of the records in advance, you can retrieve just the keys with the [**List keys**](/api/v2/key-value-store-keys-get) endpoint.

Keep in mind that you can get a maximum of 1000 keys per request, so you will need to paginate over the keys using the `exclusiveStartKey` parameter if you have more than 1000 keys. To do this, after each call, take the last record key and provide it as the `exclusiveStartKey` parameter. You can do this until you get 0 keys back.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,6 @@ You need to regularly grab SERP data about your target keywords? Apify provides

Hit `Save & Run` and you'll have the downloaded data as soon as the query finishes. To have it run at a regular frequency, you can set up the task to run on an [automatic schedule](/platform/schedules#setting-up-a-new-schedule).

To run from the API, send a [synchronous POST request](</api/v2#/reference/actor-tasks/run-task-synchronously-and-get-dataset-items/run-task-synchronously-and-get-dataset-items-(post)>) to an endpoint such as `https://api.apify.com/v2/acts/TASK_NAME_OR_ID/runs?token=YOUR_TOKEN`. Include any required input in a JSON object in the request's body.
To run from the API, send a [synchronous POST request](/api/v2/actor-task-run-sync-get-dataset-items-post) to an endpoint such as `https://api.apify.com/v2/acts/TASK_NAME_OR_ID/runs?token=YOUR_TOKEN`. Include any required input in a JSON object in the request's body.

Keep in mind that, as Google search uses a non-deterministic algorithm, output results may vary even if the input settings are exactly the same.
Loading