# Create task


```
POST 
https://api.apify.com/v2/actor-tasks
```


Create a new task with settings specified by the object passed as JSON in the POST payload.

The response is the full task object as returned by the  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. ().

## Request

<!-- -->

### Body**required**

* **actId** string required\
  **Example:** `asADASadYvn4mBZmm`

* **name** string required\
  **Example:** `my-task`

* **options** object

  * anyOf
    * TaskOptions
    * null
    **build** string | null nullable\
    **Example:** `latest`
  * **timeoutSecs** integer | null nullable\
    **Example:** `300`
  * **memoryMbytes** integer | null nullable\
    **Example:** `128`
  * **restartOnError** boolean | null nullable\
    **Example:** `false`
  * **maxItems** integer | null nullable

* **input** object

  * anyOf

    * TaskInput
    * null

    object

    The input configuration for the Actor task. This is a user-defined JSON object that will be passed to the Actor when the task is run.

    **Example:** `{"startUrls":[{"url":"https://example.com"}],"maxRequestsPerCrawl":100}`

* **title** string | null nullable

* **actorStandby** object

  * anyOf
    * ActorStandby
    * null
    **isEnabled** boolean | null nullable
  * **desiredRequestsPerActorRun** integer | null nullable
  * **maxRequestsPerActorRun** integer | null nullable
  * **idleTimeoutSecs** integer | null nullable
  * **build** string | null nullable
  * **memoryMbytes** integer | null nullable
  * **disableStandbyFieldsOverride** boolean | null nullable
  * **shouldPassActorInput** boolean | null nullable

### Status 201

**Response Headers**

* **Location**


```
{
  "data": {
    "id": "zdc3Pyhyz3m8vjDeM",
    "userId": "wRsJZtadYvn4mBZmm",
    "actId": "asADASadYvn4mBZmm",
    "name": "my-task",
    "username": "janedoe",
    "createdAt": "2018-10-26T07:23:14.855Z",
    "modifiedAt": "2018-10-26T13:30:49.578Z",
    "removedAt": null,
    "stats": {
      "totalRuns": 15
    },
    "options": {
      "build": "latest",
      "timeoutSecs": 300,
      "memoryMbytes": 128
    },
    "input": {
      "hello": "world"
    }
  }
}
```


**Schema**

* **data** object required

  * **id** string required\
    **Example:** `zdc3Pyhyz3m8vjDeM`

  * **userId** string required\
    **Example:** `wRsJZtadYvn4mBZmm`

  * **actId** string required\
    **Example:** `asADASadYvn4mBZmm`

  * **name** string required\
    **Example:** `my-task`

  * **username** string | null nullable\
    **Example:** `janedoe`

  * **createdAt** string\<date-time> required\
    **Example:** `2018-10-26T07:23:14.855Z`

  * **modifiedAt** string\<date-time> required\
    **Example:** `2018-10-26T13:30:49.578Z`

  * **removedAt** string,null\<date-time> nullable

  * **stats** object

    * anyOf
      * TaskStats
      * null
      **totalRuns** integer\
      **Example:** `15`

  * **options** object

    * anyOf
      * TaskOptions
      * null
      **build** string | null nullable\
      **Example:** `latest`
    * **timeoutSecs** integer | null nullable\
      **Example:** `300`
    * **memoryMbytes** integer | null nullable\
      **Example:** `128`
    * **restartOnError** boolean | null nullable\
      **Example:** `false`
    * **maxItems** integer | null nullable

  * **input** object

    * anyOf

      * TaskInput
      * null

      object

      The input configuration for the Actor task. This is a user-defined JSON object that will be passed to the Actor when the task is run.

      **Example:** `{"startUrls":[{"url":"https://example.com"}],"maxRequestsPerCrawl":100}`

  * **title** string | null nullable

  * **actorStandby** object

    * anyOf
      * ActorStandby
      * null
      **isEnabled** boolean | null nullable
    * **desiredRequestsPerActorRun** integer | null nullable
    * **maxRequestsPerActorRun** integer | null nullable
    * **idleTimeoutSecs** integer | null nullable
    * **build** string | null nullable
    * **memoryMbytes** integer | null nullable
    * **disableStandbyFieldsOverride** boolean | null nullable
    * **shouldPassActorInput** boolean | null nullable

  * **standbyUrl** string,null\<uri> nullable

### 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 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)`