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

## Request

### Path Parameters

* **actorTaskId** string required

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

  **Example:** `janedoe~my-task`

### Query Parameters

* **timeout** double

  Optional timeout for the run, in seconds. By default, the run uses the timeout from its configuration.

  **Example:** `60`

  **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 the memory limit from its configuration.

  **Example:** `256`

  **maxItems** double

  Specifies the maximum number of dataset items that will be charged for pay-per-result Actors. This does NOT guarantee that the Actor will return only this many items. It only ensures you won't be charged for more than this number of items. Only works for pay-per-result Actors. Value can be accessed in the actor run using `ACTOR_MAX_PAID_DATASET_ITEMS` environment variable.

  **Example:** `1000`

  **maxTotalChargeUsd** double

  Specifies the maximum cost of the run. This parameter is useful for pay-per-event Actors, 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.

  **Example:** `5`

  **restartOnError** boolean

  Determines whether the run will be restarted if it fails.

  **Example:** `false`

  **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 from its configuration (typically `latest`).

  **Example:** `0.1.234`

  **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](https://docs.apify.com/platform/integrations/webhooks).

  **Example:** `dGhpcyBpcyBqdXN0IGV4YW1wbGUK...`

  **format** string

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

  **Example:** `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.

  **Example:** `false`

  **offset** double

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

  **Example:** `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.

  **Example:** `myValue,myOtherValue`

  **omit** string

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

  **Example:** `myValue,myOtherValue`

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

  **Example:** `myValue,myOtherValue`

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

  **Example:** `myValue`

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

  **Example:** `true`

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

  **Example:** `true`

  **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 (`,`).

  **Example:** `;`

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

  **Example:** `false`

  **xmlRoot** string

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

  **Example:** `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`.

  **Example:** `item`

  **skipHeaderRow** boolean

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

  **Example:** `true`

  **skipHidden** boolean

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

  **Example:** `false`

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

  **Example:** `false`

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

  **Example:** `false`

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

  **Example:** `false`

### Body**required**

* **object** object

### Status 201

**Response Headers**

* **X-Apify-Pagination-Offset**

  The offset of the first item in the current page.

* **X-Apify-Pagination-Limit**

  The maximum number of items returned per page.

* **X-Apify-Pagination-Count**

  The number of items returned in the current page.

* **X-Apify-Pagination-Total**

  The total number of items in the dataset.


```
{}
```


**Schema**

* **object** object

### Status 400

Bad request - invalid input parameters or request body.


```
{
  "error": {
    "type": "invalid-input",
    "message": "Invalid input: The request body contains invalid data."
  }
}
```


**Schema**

* **error** object required

  * **type** string required\
    **Example:** `run-failed`
  * **message** string required\
    **Example:** `Actor run did not succeed (run ID: 55uatRrZib4xbZs, status: FAILED)`

### Status 401

Unauthorized - authentication required or invalid token.


```
{
  "error": {
    "type": "token-not-valid",
    "message": "Authentication token is not valid."
  }
}
```


**Schema**

* **error** object required

  * **type** string required\
    **Example:** `run-failed`
  * **message** string required\
    **Example:** `Actor run did not succeed (run ID: 55uatRrZib4xbZs, status: FAILED)`

### Status 403

Forbidden - insufficient permissions to perform this action.


```
{
  "error": {
    "type": "permission-denied",
    "message": "You do not have permission to perform this action."
  }
}
```


**Schema**

* **error** object required

  * **type** string required\
    **Example:** `run-failed`
  * **message** string required\
    **Example:** `Actor run did not succeed (run ID: 55uatRrZib4xbZs, status: FAILED)`

### Status 404

Not found - the requested resource does not exist.


```
{
  "error": {
    "type": "record-not-found",
    "message": "The requested resource was not found."
  }
}
```


**Schema**

* **error** object required

  * **type** string required\
    **Example:** `run-failed`
  * **message** string required\
    **Example:** `Actor run did not succeed (run ID: 55uatRrZib4xbZs, status: FAILED)`

### Status 405

Method not allowed.


```
{
  "error": {
    "type": "method-not-allowed",
    "message": "This API end-point can only be accessed using the following HTTP methods: OPTIONS,GET"
  }
}
```


**Schema**

* **error** object required

  * **type** string required\
    **Example:** `run-failed`
  * **message** string required\
    **Example:** `Actor run did not succeed (run ID: 55uatRrZib4xbZs, status: FAILED)`

### Status 413

Payload too large - the request body exceeds the size limit.


```
{
  "error": {
    "type": "request-too-large",
    "message": "The POST payload is too large (limit: 9437184 bytes, actual length: 10485760 bytes)."
  }
}
```


**Schema**

* **error** object required

  * **type** string required\
    **Example:** `run-failed`
  * **message** string required\
    **Example:** `Actor run did not succeed (run ID: 55uatRrZib4xbZs, status: FAILED)`

### Status 415

Unsupported media type - the Content-Encoding of the request is not supported.


```
{
  "error": {
    "type": "unsupported-content-encoding",
    "message": "Content-Encoding \"bla\" is not supported."
  }
}
```


**Schema**

* **error** object required

  * **type** string required\
    **Example:** `run-failed`
  * **message** string required\
    **Example:** `Actor run did not succeed (run ID: 55uatRrZib4xbZs, status: FAILED)`

### Status 429

Too many requests - rate limit exceeded.


```
{
  "error": {
    "type": "rate-limit-exceeded",
    "message": "You have exceeded the rate limit. Please try again later."
  }
}
```


**Schema**

* **error** object required

  * **type** string required\
    **Example:** `run-failed`
  * **message** string required\
    **Example:** `Actor run did not succeed (run ID: 55uatRrZib4xbZs, status: FAILED)`