--- title: "Run task" method: POST path: "/v2/actor-tasks/{actorTaskId}/runs" tags: ["Actor tasks"] --- # Run task `POST /v2/actor-tasks/{actorTaskId}/runs` Runs an Actor task and immediately returns without waiting for the run to finish. 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 Actor's input schema if not defined by the task). The response is the Actor Run object as returned by the [Get run](#/reference/actor-runs/run-object-and-its-storages/get-run) endpoint. If you want to wait for the run to finish and receive the actual output of the Actor run as the response, use one of the [Run task synchronously](#/reference/actor-tasks/run-task-synchronously) API endpoints instead. To fetch the Actor run results that are typically stored in the default dataset, you'll need to pass the ID received in the `defaultDatasetId` field received in the response JSON to the [Get dataset items](#/reference/datasets/item-collection/get-items) API endpoint. ## Path parameters - `actorTaskId` string, required ## Query parameters - `timeout` number, double - `memory` number, double - `maxItems` number, double - `maxTotalChargeUsd` number, double - `restartOnError` boolean - `build` string - `waitForFinish` number, double - `webhooks` string, byte ## Request body - object ## Response `201` - object - `data` Run, required — Represents an Actor run and its associated data. - `id` string, required — Unique identifier of the Actor run. - `actId` string, required — ID of the Actor that was run. - `userId` string, required — ID of the user who started the run. - `actorTaskId` string, nullable — ID of the Actor task, if the run was started from a task. - `startedAt` string, date-time, required — Time when the Actor run started. - `finishedAt` string, date-time, nullable — Time when the Actor run finished. - `status` 'READY' | 'RUNNING' | 'SUCCEEDED' | 'FAILED' | 'TIMING-OUT' | 'TIMED-OUT' | 'ABORTING' | 'ABORTED', required — Status of an Actor job (run or build). - `statusMessage` string, nullable — Detailed message about the run status. - `isStatusMessageTerminal` boolean, nullable — Whether the status message is terminal (final). - `meta` RunMeta, required - `origin` 'DEVELOPMENT' | 'WEB' | 'API' | 'SCHEDULER' | 'TEST' | 'WEBHOOK' | 'ACTOR' | 'CLI' | 'CI' | 'STANDBY' | 'MCP', required - `clientIp` string, nullable — IP address of the client that started the run. - `userAgent` string, nullable — User agent of the client that started the run. - `scheduleId` string, nullable — ID of the schedule that triggered the run. - `scheduledAt` string, date-time, nullable — Time when the run was scheduled. - `pricingInfo` union - PayPerEventActorPricingInfo - `apifyMarginPercentage` number, required — In [0, 1], fraction of pricePerUnitUsd that goes to Apify - `createdAt` string, date-time, required — When this pricing info record has been created - `startedAt` string, date-time, required — Since when is this pricing info record effective for a given Actor - `notifiedAboutFutureChangeAt` string, date-time, nullable - `notifiedAboutChangeAt` string, date-time, nullable - `reasonForChange` string, nullable - `isPriceChangeNotificationSuppressed` boolean - `forceContainsSignificantPriceChange` boolean - `pricingModel` 'PAY_PER_EVENT', required - `pricingPerEvent` object, required - `actorChargeEvents` object - `minimalMaxTotalChargeUsd` number, nullable - PricePerDatasetItemActorPricingInfo - `apifyMarginPercentage` number, required — In [0, 1], fraction of pricePerUnitUsd that goes to Apify - `createdAt` string, date-time, required — When this pricing info record has been created - `startedAt` string, date-time, required — Since when is this pricing info record effective for a given Actor - `notifiedAboutFutureChangeAt` string, date-time, nullable - `notifiedAboutChangeAt` string, date-time, nullable - `reasonForChange` string, nullable - `isPriceChangeNotificationSuppressed` boolean - `forceContainsSignificantPriceChange` boolean - `pricingModel` 'PRICE_PER_DATASET_ITEM', required - `unitName` string, required — Name of the unit that is being charged - `pricePerUnitUsd` number — Price per unit in USD. Mutually exclusive with `tieredPricing` - exactly one of the two is present on a pricing record. - `tieredPricing` TieredPricingPerDatasetItem — Tiered price-per-dataset-item pricing, keyed by subscription tier (e.g. `FREE`, `BRONZE`, `SILVER`, `GOLD`, `PLATINUM`, `DIAMOND`). The actual price applied to a run is resolved from the user's tier. - FlatPricePerMonthActorPricingInfo - `apifyMarginPercentage` number, required — In [0, 1], fraction of pricePerUnitUsd that goes to Apify - `createdAt` string, date-time, required — When this pricing info record has been created - `startedAt` string, date-time, required — Since when is this pricing info record effective for a given Actor - `notifiedAboutFutureChangeAt` string, date-time, nullable - `notifiedAboutChangeAt` string, date-time, nullable - `reasonForChange` string, nullable - `isPriceChangeNotificationSuppressed` boolean - `forceContainsSignificantPriceChange` boolean - `pricingModel` 'FLAT_PRICE_PER_MONTH', required - `trialMinutes` integer, required — For how long this Actor can be used for free in trial period - `pricePerUnitUsd` number, required — Monthly flat price in USD - FreeActorPricingInfo - `apifyMarginPercentage` number, required — In [0, 1], fraction of pricePerUnitUsd that goes to Apify - `createdAt` string, date-time, required — When this pricing info record has been created - `startedAt` string, date-time, required — Since when is this pricing info record effective for a given Actor - `notifiedAboutFutureChangeAt` string, date-time, nullable - `notifiedAboutChangeAt` string, date-time, nullable - `reasonForChange` string, nullable - `isPriceChangeNotificationSuppressed` boolean - `forceContainsSignificantPriceChange` boolean - `pricingModel` 'FREE', required - `stats` RunStats, required - `inputBodyLen` integer, nullable - `migrationCount` integer - `rebootCount` integer - `restartCount` integer - `resurrectCount` integer - `memAvgBytes` number - `memMaxBytes` integer - `memCurrentBytes` integer - `cpuAvgUsage` number - `cpuMaxUsage` number - `cpuCurrentUsage` number - `netRxBytes` integer - `netTxBytes` integer - `durationMillis` integer - `runTimeSecs` number - `metamorph` integer - `computeUnits` number - `chargedEventCounts` object — A map of charged event types to their counts. The keys are event type identifiers defined by the Actor's pricing model (pay-per-event), and the values are the number of times each event was charged during this run. - `options` RunOptions, required - `build` string, required - `timeoutSecs` integer, required - `memoryMbytes` integer, required - `diskMbytes` integer, required - `maxItems` integer, nullable - `maxTotalChargeUsd` number, nullable - `buildId` string, required — ID of the Actor build used for this run. - `exitCode` integer, nullable — Exit code of the Actor run process. - `generalAccess` 'ANYONE_WITH_ID_CAN_READ' | 'ANYONE_WITH_NAME_CAN_READ' | 'FOLLOW_USER_SETTING' | 'RESTRICTED', required — Defines the general access level for the resource. - `defaultKeyValueStoreId` string, required — ID of the default key-value store for this run. - `defaultDatasetId` string, required — ID of the default dataset for this run. - `defaultRequestQueueId` string, required — ID of the default request queue for this run. - `storageIds` object — A map of aliased storage IDs associated with this run, grouped by storage type. - `datasets` object — Aliased dataset IDs for this run. - `default` string — ID of the default dataset for this run. - `keyValueStores` object — Aliased key-value store IDs for this run. - `default` string — ID of the default key-value store for this run. - `requestQueues` object — Aliased request queue IDs for this run. - `default` string — ID of the default request queue for this run. - `buildNumber` string, nullable — Build number of the Actor build used for this run. - `containerUrl` string, uri — URL of the container running the Actor. - `isContainerServerReady` boolean, nullable — Whether the container's HTTP server is ready to accept requests. - `gitBranchName` string, nullable — Name of the git branch used for the Actor build. - `usage` RunUsage - `ACTOR_COMPUTE_UNITS` number, nullable - `DATASET_READS` integer, nullable - `DATASET_WRITES` integer, nullable - `KEY_VALUE_STORE_READS` integer, nullable - `KEY_VALUE_STORE_WRITES` integer, nullable - `KEY_VALUE_STORE_LISTS` integer, nullable - `REQUEST_QUEUE_READS` integer, nullable - `REQUEST_QUEUE_WRITES` integer, nullable - `DATA_TRANSFER_INTERNAL_GBYTES` number, nullable - `DATA_TRANSFER_EXTERNAL_GBYTES` number, nullable - `PROXY_RESIDENTIAL_TRANSFER_GBYTES` number, nullable - `PROXY_SERPS` integer, nullable - `usageTotalUsd` number, nullable — Total cost in USD for this run. Represents what you actually pay. For run owners: includes platform usage (compute units) and/or event costs depending on the Actor's pricing model. For run non-owners: only available for Pay-Per-Event Actors (event costs only). Requires authentication token to access. - `usageUsd` RunUsageUsd — Resource usage costs in USD. All values are monetary amounts in US dollars. - `ACTOR_COMPUTE_UNITS` number, nullable - `DATASET_READS` number, nullable - `DATASET_WRITES` number, nullable - `KEY_VALUE_STORE_READS` number, nullable - `KEY_VALUE_STORE_WRITES` number, nullable - `KEY_VALUE_STORE_LISTS` number, nullable - `REQUEST_QUEUE_READS` number, nullable - `REQUEST_QUEUE_WRITES` number, nullable - `DATA_TRANSFER_INTERNAL_GBYTES` number, nullable - `DATA_TRANSFER_EXTERNAL_GBYTES` number, nullable - `PROXY_RESIDENTIAL_TRANSFER_GBYTES` number, nullable - `PROXY_SERPS` number, nullable - `metamorphs` Metamorph[], nullable — List of metamorph events that occurred during the run. - `createdAt` string, date-time, required — Time when the metamorph occurred. - `actorId` string, required — ID of the Actor that the run was metamorphed to. - `buildId` string, required — ID of the build used for the metamorphed Actor. - `inputKey` string, nullable — Key of the input record in the key-value store. - `platformUsageBillingModel` string — Indicates which party covers platform usage costs for this run. ## Other responses - `400` — Bad request - invalid input parameters or request body. - `401` — Unauthorized - authentication required or invalid token. - `402` — Payment required - the user has exceeded their usage limit, does not have enough credits, or the request lacks authentication and payment credentials. - `403` — Forbidden - insufficient permissions to perform this action. - `404` — Not found - the requested resource does not exist. - `405` — Method not allowed. - `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)