Run task synchronously and get dataset items

POST 
https://api.apify.com/v2/actor-tasks/:actorTaskId/run-sync-get-dataset-items

Runs an Actor task and synchronously returns its dataset items.

The run must finish in 300 seconds otherwise the HTTP request fails with a timeout error (this won't abort the run itself).

Optionally, you can override the Actor input configuration by passing a JSON object as the POST payload and setting the Content-Type: application/json HTTP header.

Note that if the object in the POST payload does not define a particular input property, the Actor run uses the default value defined by the task (or the Actor's input schema if not defined by the task).

You can send all the same options in parameters as the Get Dataset Items API endpoint.

Beware that it might be impossible to maintain an idle HTTP connection for an extended period, due to client timeout or network conditions. Make sure your HTTP client is configured to have a long enough connection timeout.

If the connection breaks, you will not receive any information about the run and its status.

Input fields from Actor task configuration can be overloaded with values passed as the POST payload.

Just make sure to specify the Content-Type header as application/json and that the input is an object.

To run the task asynchronously, use the Run task API endpoint instead.

Request

Path Parameters

actorTaskId stringrequired

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

Query Parameters

timeout double

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

memory double

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

maxItems double

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

maxTotalChargeUsd double

Specifies the maximum cost of the task run. This is useful for pay-per-event tasks, as it allows you to limit the amount charged to your subscription. You can access the maximum cost in your Actor by using the ACTOR_MAX_TOTAL_CHARGE_USD environment variable.

build string

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

webhooks string

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.

format string

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

clean boolean

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 double

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

limit double

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

fields string

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

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

unwind string

A comma-separated list of fields which should be unwound, in order which they should be processed. Each field should be either an array or an object. 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

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

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

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

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

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

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

xmlRow string

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

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

skipHidden boolean

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

skipEmpty boolean

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

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

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.

application/json

Bodyrequired

objectobject

Responses

201

Response Headers

X-Apify-Pagination-Offset
X-Apify-Pagination-Limit
X-Apify-Pagination-Count
X-Apify-Pagination-Total

application/json

Schema

Schema

objectobject

Example (auto)

{}

400

Response Headers

application/json

Schema

Schema

error objectrequired
typestringrequired
Example: run-failed
messagestringrequired
Example: Actor run did not succeed (run ID: 55uatRrZib4xbZs, status: FAILED)

Example (auto)

{
  "error": {
    "type": "run-failed",
    "message": "Actor run did not succeed (run ID: 55uatRrZib4xbZs, status: FAILED)"
  }
}

Authorization: http

name: httpBearertype: httpscheme: bearerdescription: API authentication token.

• CLI
• JavaScript
• Python
• PHP
• Java
• C
• C#
• Go
• Rust
• Node.js
• Ruby
• PowerShell
• Dart
• Objective-C
• OCaml
• R
• Swift
• Kotlin

• CURL

curl -L 'https://api.apify.com/v2/actor-tasks/:actorTaskId/run-sync-get-dataset-items' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <token>' \
-d '{}'

Request Collapse all

Base URL

https://api.apify.com

Auth

Security Scheme

httpBearerapiKey

Bearer Token

Parameters

actorTaskId — pathrequired

timeout — query

memory — query

maxItems — query

maxTotalChargeUsd — query

build — query

webhooks — query

format — query

clean — query

---truefalse

offset — query

limit — query

fields — query

omit — query

unwind — query

flatten — query

desc — query

---truefalse

attachment — query

---truefalse

delimiter — query

bom — query

---truefalse

xmlRoot — query

xmlRow — query

skipHeaderRow — query

---truefalse

skipHidden — query

---truefalse

skipEmpty — query

---truefalse

simplified — query

---truefalse

skipFailedPages — query

---truefalse

Body required

• Example (from schema)
• Example

{}

ResponseClear

Click the Send API Request button above and see the response here!