--- title: "Run Actor" method: POST path: "/v2/actors/{actorId}/runs" tags: ["Actors/Actor runs"] --- # Run Actor `POST /v2/actors/{actorId}/runs` Runs an Actor and immediately returns without waiting for the run to finish. The POST payload including its `Content-Type` header is passed as `INPUT` to the Actor (usually `application/json`). The Actor is started with the default options; you can override them using various URL query parameters. The response is the Run object as returned by the [Get run](#/reference/actor-runs/run-object-and-its-storages/get-run) API endpoint. If you want to wait for the run to finish and receive the actual output of the Actor as the response, please use one of the [Run Actor synchronously](#/reference/actors/run-actor-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 - `actorId` 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 - `forcePermissionLevel` 'LIMITED_PERMISSIONS' | 'FULL_PERMISSIONS' ## Request body - object ## Response `201` - RunResponse - `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. - `408` — The HTTP request exceeded the timeout limit - `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)