---
title: "Create task"
method: POST
path: "/v2/actor-tasks"
tags: ["Actor tasks"]
---

# Create task

`POST /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
[Get task](/api/v2/actor-task-get) 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

- object
  - `actId` string, required
  - `name` string
  - `options` TaskOptions
    - `build` string, nullable
    - `timeoutSecs` integer, nullable
    - `memoryMbytes` integer, nullable
    - `maxItems` integer, nullable
    - `maxTotalChargeUsd` number, nullable
    - `restartOnError` boolean, nullable
  - `input` TaskInput — 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.
  - `title` string, nullable
  - `actorStandby` ActorStandby
    - `isEnabled` boolean, nullable — Whether standby mode is enabled for the Actor.
    - `desiredRequestsPerActorRun` integer, nullable — Target number of concurrent HTTP requests a single run is configured to handle.
    - `maxRequestsPerActorRun` integer, nullable — Maximum number of concurrent HTTP requests that can be routed to a single run.
    - `idleTimeoutSecs` integer, nullable — In seconds, how long a run can stay idle without incoming requests before it's terminated.
    - `build` string, nullable — Which build to run in standby mode. Either a build tag or a version number.
    - `memoryMbytes` integer, nullable — In MB, the amount of memory allocated to the run.
    - `disableStandbyFieldsOverride` boolean, nullable — If `true`, prevents the standby mode configuration from being overridden elsewhere.
    - `shouldPassActorInput` boolean, nullable — Whether to pass the Actor's input to the standby run. If `false`, the standby runs start with no input.

## Response `201`

- TaskResponse — Response containing Actor task data.
  - `data` Task, required
    - `id` string, required
    - `userId` string, required
    - `actId` string, required
    - `name` string, required
    - `username` string, nullable
    - `createdAt` string, date-time, required
    - `modifiedAt` string, date-time, required
    - `removedAt` string, date-time, nullable
    - `stats` TaskStats
      - `totalRuns` integer
    - `options` TaskOptions
      - `build` string, nullable
      - `timeoutSecs` integer, nullable
      - `memoryMbytes` integer, nullable
      - `maxItems` integer, nullable
      - `maxTotalChargeUsd` number, nullable
      - `restartOnError` boolean, nullable
    - `input` TaskInput — 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.
    - `title` string, nullable
    - `actorStandby` ActorStandby
      - `isEnabled` boolean, nullable — Whether standby mode is enabled for the Actor.
      - `desiredRequestsPerActorRun` integer, nullable — Target number of concurrent HTTP requests a single run is configured to handle.
      - `maxRequestsPerActorRun` integer, nullable — Maximum number of concurrent HTTP requests that can be routed to a single run.
      - `idleTimeoutSecs` integer, nullable — In seconds, how long a run can stay idle without incoming requests before it's terminated.
      - `build` string, nullable — Which build to run in standby mode. Either a build tag or a version number.
      - `memoryMbytes` integer, nullable — In MB, the amount of memory allocated to the run.
      - `disableStandbyFieldsOverride` boolean, nullable — If `true`, prevents the standby mode configuration from being overridden elsewhere.
      - `shouldPassActorInput` boolean, nullable — Whether to pass the Actor's input to the standby run. If `false`, the standby runs start with no input.
    - `standbyUrl` string, uri, nullable

## Other responses

- `400` — Bad request - invalid input parameters or request body.
- `401` — Unauthorized - authentication required or invalid token.
- `403` — Forbidden - insufficient permissions to perform this action.
- `404` — Not found - the requested resource does not exist.
- `405` — Method not allowed.
- `409` — Conflict - the request could not be completed due to a conflict with the current state of the resource.
- `413` — Payload too large - the request body exceeds the size limit.
- `415` — Unsupported media type - the Content-Encoding of the request is not supported.
- `429` — Too many requests - rate limit exceeded.

---

[API](https://skmtc.net/apify/apis/apify-api.md) · [All operations](https://skmtc.net/apify/apis/apify-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/apify/apify-api/versions/01a71794279b/schema)