--- title: "Create Actor" method: POST path: "/v2/actors" tags: ["Actors"] --- # Create Actor `POST /v2/actors` Creates an Actor with the settings specified in an `Actor` object passed as JSON in the POST payload. Returns the full `Actor` object, the same as the [Get Actor](/api/v2/actor-get) endpoint. In the HTTP request, set the `Content-Type` header to `application/json`. ### Define a source code version An Actor must specify at least one version of the source code. For details, see [Actor versions](/api/v2/actors-actor-versions). ### Create a public Actor To make your Actor [public](https://docs.apify.com/platform/actors/publishing): - Set `isPublic` to `true`. - Provide `title` and `categories`. For reference, see [constants from the `apify-shared-js` package](https://github.com/apify/apify-shared-js/blob/2d43ebc41ece9ad31cd6525bd523fb86939bf860/packages/consts/src/consts.ts#L452-L471) ## Request body - CreateActorRequest - `name` string, nullable — The identifier of the Actor. Use lowercase letters, numbers, and hyphens. Spaces or special characters aren't allowed. Must be unique across your account. - `description` string, nullable — Short description of the Actor, displayed in Apify Store and Console. - `title` string, nullable — Human-readable name of the Actor, displayed in Apify Store and Console. Can contain spaces and capital letters. Recommended length is 40-50 characters. You can change this title without affecting the Actor's URL or SEO. - `isPublic` boolean, nullable — Whether the Actor is available to users in Apify Store. If `false`, the Actor is private and only visible to you. - `seoTitle` string, nullable — Name of the Actor to display by search engines such as Google. Can be different from the Actor's name displayed in Apify Store and Console. Recommended length is 40-50 characters. - `seoDescription` string, nullable — Description of the Actor to display by search engines such as Google. Recommended length is 140-156 characters. - `restartOnError` boolean - `versions` Version[], nullable — An array of `Version` objects. Each object represents a specific version of the Actor's source code: its location, builds, and environment configuration. - `versionNumber` string, required — The version number of the Actor. Two numbers separated by a dot, that represent the `MAJOR.MINOR` part of the semantic versioning. - `sourceType` 'SOURCE_FILES' | 'GIT_REPO' | 'TARBALL' | 'GITHUB_GIST' | 'SOURCE_CODE', required - `envVars` EnvVar[], nullable — Environment variables for the version. - `name` string, required — The name of the environment variable. - `value` string — The value of the environment variable. If `isSecret` is `true`, this value isn't returned by the API. - `isSecret` boolean, nullable — Whether the environment variable is encrypted. Secret values aren't returned by the API. - `applyEnvVarsToBuild` boolean, nullable — Whether to inject the environment variables at build time. - `buildTag` string, nullable — The tag name to apply to a successful build of this version. Can be `null` when the version has no build tag. - `sourceFiles` union[] - union - SourceCodeFile — Represents a single file in the Actor's source code. - `format` 'BASE64' | 'TEXT' - `content` string — The contents of the file. Interpreted based on the value of `format`. - `name` string, required — The path of the file relative to the Actor's root directory. - SourceCodeFolder — Represents a folder in the Actor's source code structure. Distinguished from SourceCodeFile by the presence of the `folder` property set to `true`. - `name` string, required — The path of the folder relative to the Actor's root directory. - `folder` boolean, required — Whether it's a folder. Distinguishes folders from files. - `gitRepoUrl` string, nullable — URL of the Git repository to clone the source code from. Applies when the `sourceType` is `GIT_REPO`. - `tarballUrl` string, nullable — URL to download the source code from as a tarball or ZIP file. Applies when the `sourceType` is `TARBALL`. - `gitHubGistUrl` string, nullable — URL of the GitHub Gist to clone the source code from. Applies when the `sourceType` is `GITHUB_GIST`. - `pricingInfos` ActorRunPricingInfo[] - 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 - `categories` string[], nullable — A list of categories that best define the Actor. Reflected in Apify Store's search and filtering options. - `defaultRunOptions` DefaultRunOptions — The default settings applied to an Actor run. Can be overridden elsewhere. - `build` string — Which build to run. Either a build tag or a version number. - `timeoutSecs` integer — Timeout in seconds. 0 if no timeout. - `memoryMbytes` integer — In MB, the amount of memory allocated to the run. - `restartOnError` boolean — Whether to automatically restart the run if it fails. - `maxItems` integer, nullable — Maximum number of items the run might produce. - `forcePermissionLevel` 'LIMITED_PERMISSIONS' | 'FULL_PERMISSIONS' — Determines the permission level that the Actor requires to run. For details, see [Actor permissions](https://docs.apify.com/platform/actors/development/permissions). - `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. - `exampleRunInput` ExampleRunInput - `body` string — Sample input, serialized as a string. - `contentType` string — MIME type of `body`. - `isDeprecated` boolean, nullable — Whether the Actor is deprecated. ## Response `201` - ActorResponse — Response containing Actor data. - `data` Actor, required - `id` string, required — The ID of the Actor. - `userId` string, required — The ID of the user who owns the Actor. - `name` string, required — The name of the Actor. - `username` string, required — The username of the Actor owner. - `description` string, nullable — Short description of the Actor, displayed in Apify Store and Console. - `restartOnError` boolean - `isPublic` boolean, required — Whether the Actor is available to users in Apify Store. - `actorPermissionLevel` 'LIMITED_PERMISSIONS' | 'FULL_PERMISSIONS' — Determines the permission level that the Actor requires to run. For details, see [Actor permissions](https://docs.apify.com/platform/actors/development/permissions). - `createdAt` string, date-time, required — The date and time the Actor was created. Follows the ISO 8601 format. - `modifiedAt` string, date-time, required — The date and time the Actor was last modified. Follows the ISO 8601 format. - `stats` ActorStats, required — Usage statistics and Apify Store metrics for the Actor. - `totalBuilds` integer — The total number of builds of the Actor. - `totalRuns` integer — The total number of runs of the Actor. - `totalUsers` integer — The total number of Actor users, including its owner. - `totalUsers7Days` integer — The number of active users of the Actor in the last 7 days. - `totalUsers30Days` integer — The number of active users of the Actor in the last 30 days. - `totalUsers90Days` integer — The number of active users of the Actor in the last 90 days. - `totalMetamorphs` integer — The total number of times a run of another Actor was [metamorphed](https://docs.apify.com/platform/actors/development/programming-interface/metamorph) into this Actor. - `lastRunStartedAt` string, date-time — The date and time the most recent run of the Actor started. - `actorReviewCount` integer — The number of reviews the Actor has received in Apify Store. - `actorReviewRating` number — The average rating of the Actor in Apify Store. - `bookmarkCount` integer — The number of users who bookmarked the Actor in Apify Store. - `publicActorRunStats30Days` object — Run status counts from the last 30 days. Only for public Actors. Excludes runs started by the Actor's owner. - `ABORTED` integer — The number of runs that were aborted. - `FAILED` integer — The number of runs that failed. - `SUCCEEDED` integer — The number of runs that succeeded. - `TIMED-OUT` integer — The number of runs that timed out. - `TOTAL` integer — The total number of runs. - `versions` Version[], required — An array of `Version` objects. Each object represents a specific version of the Actor's source code: its location, builds, and environment configuration. - `versionNumber` string, required — The version number of the Actor. Two numbers separated by a dot, that represent the `MAJOR.MINOR` part of the semantic versioning. - `sourceType` 'SOURCE_FILES' | 'GIT_REPO' | 'TARBALL' | 'GITHUB_GIST' | 'SOURCE_CODE', required - `envVars` EnvVar[], nullable — Environment variables for the version. - `name` string, required — The name of the environment variable. - `value` string — The value of the environment variable. If `isSecret` is `true`, this value isn't returned by the API. - `isSecret` boolean, nullable — Whether the environment variable is encrypted. Secret values aren't returned by the API. - `applyEnvVarsToBuild` boolean, nullable — Whether to inject the environment variables at build time. - `buildTag` string, nullable — The tag name to apply to a successful build of this version. Can be `null` when the version has no build tag. - `sourceFiles` union[] - union - SourceCodeFile — Represents a single file in the Actor's source code. - `format` 'BASE64' | 'TEXT' - `content` string — The contents of the file. Interpreted based on the value of `format`. - `name` string, required — The path of the file relative to the Actor's root directory. - SourceCodeFolder — Represents a folder in the Actor's source code structure. Distinguished from SourceCodeFile by the presence of the `folder` property set to `true`. - `name` string, required — The path of the folder relative to the Actor's root directory. - `folder` boolean, required — Whether it's a folder. Distinguishes folders from files. - `gitRepoUrl` string, nullable — URL of the Git repository to clone the source code from. Applies when the `sourceType` is `GIT_REPO`. - `tarballUrl` string, nullable — URL to download the source code from as a tarball or ZIP file. Applies when the `sourceType` is `TARBALL`. - `gitHubGistUrl` string, nullable — URL of the GitHub Gist to clone the source code from. Applies when the `sourceType` is `GITHUB_GIST`. - `pricingInfos` ActorRunPricingInfo[] - 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 - `defaultRunOptions` DefaultRunOptions, required — The default settings applied to an Actor run. Can be overridden elsewhere. - `build` string — Which build to run. Either a build tag or a version number. - `timeoutSecs` integer — Timeout in seconds. 0 if no timeout. - `memoryMbytes` integer — In MB, the amount of memory allocated to the run. - `restartOnError` boolean — Whether to automatically restart the run if it fails. - `maxItems` integer, nullable — Maximum number of items the run might produce. - `forcePermissionLevel` 'LIMITED_PERMISSIONS' | 'FULL_PERMISSIONS' — Determines the permission level that the Actor requires to run. For details, see [Actor permissions](https://docs.apify.com/platform/actors/development/permissions). - `exampleRunInput` ExampleRunInput - `body` string — Sample input, serialized as a string. - `contentType` string — MIME type of `body`. - `isDeprecated` boolean, nullable — Whether the Actor is deprecated. - `deploymentKey` string — The Actor's public SSH key, used as a deployment key for private Git repositories. - `title` string, nullable — Human-readable name of the Actor, displayed in Apify Store and Console. - `taggedBuilds` TaggedBuilds — A dictionary mapping build tag names (e.g., "latest", "beta") to their build information. - `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. - `readmeSummary` string — An AI-generated Markdown summary of the Actor's README, optimized for search and AI agents. Contains an overview and a list of use cases. Generated only for public Actors. - `seoTitle` string, nullable — Name of the Actor to display by search engines such as Google. Can be different from the Actor's name displayed in Apify Store and Console. - `seoDescription` string, nullable — Description of the Actor to display by search engines such as Google. - `pictureUrl` string, nullable — URL of the Actor's icon, displayed on the Actor's page in Apify Store and Console. - `standbyUrl` string, nullable — URL for sending requests to the Actor in Standby mode. `null` if the Standby mode isn't enabled. - `notice` 'NONE' | 'RESIDENTIAL_PROXY_REQUIRED' | 'UNDER_MAINTENANCE', nullable — A warning displayed on the Actor's page in Apify Store and Console. Can be set by the Actor's developer or automatically by Apify's quality checks. - `categories` string[] — A list of categories that best define the Actor. Reflected in Apify Store's search and filtering options. - `isCritical` boolean — Whether the Actor is maintained by Apify. - `isGeneric` boolean — Whether the Actor is intended for developers. Set by Apify. - `isSourceCodeHidden` boolean — Whether the Actor's source files are hidden on its detail page. - `hasNoDataset` boolean — Whether the Actor stores results in a dataset. Set by Apify. ## 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. - `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)