Skip to main content

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 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.

Create a public Actor

To make your Actor public:

Request

Bodyrequired

  • name string | null 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.


    Example: instagram-scraper
  • description string | null nullable

    Short description of the Actor, displayed in Apify Store and Console.


    Example: This scraper extracts posts and comments from Instagram.
  • title string | null 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.


    Example: Instagram scraper
  • isPublic boolean | null nullable

    Whether the Actor is available to users in Apify Store. If false, the Actor is private and only visible to you.


    Example: false
  • seoTitle string | null 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.


    Example: Free Instagram scraper
  • seoDescription string | null nullable

    Description of the Actor to display by search engines such as Google. Recommended length is 140-156 characters.


    Example: The best scraper for Instagram
  • restartOnError boolean deprecated
    Example: false
  • versions object

    An array of Version objects. Each object represents a specific version of the Actor's source code: its location, builds, and environment configuration.

      anyOf
    • 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.

      Possible values: Value must match regular expression ^([0-9]|[1-9][0-9])\.([0-9]|[1-9][0-9])$


      Example: 0.0
    • sourceType object required

      Where the source code of the version lives.

        anyOf
      • VersionSourceType (string)

        Possible values: [SOURCE_FILES, GIT_REPO, TARBALL, GITHUB_GIST, SOURCE_CODE]

    • envVars object

      Environment variables for the version.

        anyOf
      • name string required

        The name of the environment variable.


        Example: MY_ENV_VAR
      • value string

        The value of the environment variable. If isSecret is true, this value isn't returned by the API.


        Example: my-value
      • isSecret boolean | null nullable

        Whether the environment variable is encrypted. Secret values aren't returned by the API.


        Example: false
    • applyEnvVarsToBuild boolean | null nullable

      Whether to inject the environment variables at build time.


      Example: false
    • buildTag string | null nullable

      The tag name to apply to a successful build of this version. Can be null when the version has no build tag.


      Example: latest
    • sourceFiles object[]

      Applies when the sourceType is SOURCE_FILES. Represents the Actor's file structure as an array of files and folders.

        anyOf
      • format SourceCodeFileFormat (string)

        Format of the file's content, TEXT for plain text and BASE64 for encoded content.

        Possible values: [BASE64, TEXT]


        Example: TEXT
      • content string

        The contents of the file. Interpreted based on the value of format.


        Example: console.log('This is the main.js file');
      • name string required

        The path of the file relative to the Actor's root directory.


        Example: src/main.js
    • gitRepoUrl string | null nullable

      URL of the Git repository to clone the source code from. Applies when the sourceType is GIT_REPO.

    • tarballUrl string | null nullable

      URL to download the source code from as a tarball or ZIP file. Applies when the sourceType is TARBALL.

    • gitHubGistUrl string | null nullable

      URL of the GitHub Gist to clone the source code from. Applies when the sourceType is GITHUB_GIST.

  • pricingInfos object[]
      oneOf
    • 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,null<date-time> nullable
    • notifiedAboutChangeAt string,null<date-time> nullable
    • reasonForChange string | null nullable
    • isPriceChangeNotificationSuppressed boolean
    • forceContainsSignificantPriceChange boolean
    • pricingModel string required
      Constant value: PAY_PER_EVENT
    • pricingPerEvent object required
      • actorChargeEvents object
        • property name* ActorChargeEvent

          Definition of a single chargeable event for a pay-per-event Actor. Each event is either flat-priced (eventPriceUsd is set) or tier-priced (eventTieredPricingUsd is set); the two are mutually exclusive.

          • eventTitle string required

            Human-readable title shown to users in the billing UI.

          • eventDescription string required

            Human-readable description of what triggers this event.

          • eventPriceUsd number

            Flat price per event in USD. Present only for non-tiered events. Mutually exclusive with eventTieredPricingUsd.

          • eventTieredPricingUsd object

            Tiered price-per-event pricing for a single charge event, keyed by subscription tier (e.g. FREE, BRONZE, SILVER, GOLD, PLATINUM, DIAMOND). The actual price applied is resolved from the user's tier.

            • property name* TieredPricingPerEventEntry

              A single tier's price-per-event entry.

              • tieredEventPriceUsd number required

                Price per event in USD for this tier.

          • isPrimaryEvent boolean

            Whether this event is the Actor's primary chargeable event.

          • isOneTimeEvent boolean

            Whether this event can only be charged once per Actor run.

    • minimalMaxTotalChargeUsd number | null nullable
  • categories string[] nullable

    A list of categories that best define the Actor. Reflected in Apify Store's search and filtering options.


    Example: ["SOCIAL_MEDIA"]
  • defaultRunOptions object

    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.


      Example: latest
    • timeoutSecs integer

      Timeout in seconds. 0 if no timeout.


      Example: 3600
    • memoryMbytes integer

      In MB, the amount of memory allocated to the run.


      Example: 2048
    • restartOnError boolean

      Whether to automatically restart the run if it fails.


      Example: false
    • maxItems integer | null nullable

      Maximum number of items the run might produce.

    • forcePermissionLevel object
        anyOf
      • ActorPermissionLevel (string)

        Determines the permission level that the Actor requires to run. For details, see Actor permissions.

        Possible values: [LIMITED_PERMISSIONS, FULL_PERMISSIONS]


        Example: LIMITED_PERMISSIONS
  • actorStandby object

    The configuration of the Actor's standby mode. For details, see Standby mode.

      anyOf
    • isEnabled boolean | null nullable

      Whether standby mode is enabled for the Actor.

    • desiredRequestsPerActorRun integer | null nullable

      Target number of concurrent HTTP requests a single run is configured to handle.

    • maxRequestsPerActorRun integer | null nullable

      Maximum number of concurrent HTTP requests that can be routed to a single run.

    • idleTimeoutSecs integer | null nullable

      In seconds, how long a run can stay idle without incoming requests before it's terminated.

    • build string | null nullable

      Which build to run in standby mode. Either a build tag or a version number.

    • memoryMbytes integer | null nullable

      In MB, the amount of memory allocated to the run.

    • disableStandbyFieldsOverride boolean | null nullable

      If true, prevents the standby mode configuration from being overridden elsewhere.

    • shouldPassActorInput boolean | null nullable

      Whether to pass the Actor's input to the standby run. If false, the standby runs start with no input.

  • exampleRunInput object

    Sample input payload that demonstrates what a typical run input for an Actor looks like. Used when no explicit input for a run is provided.

      anyOf
    • body string

      Sample input, serialized as a string.


      Example: { "helloWorld": 123 }
    • contentType string

      MIME type of body.


      Example: application/json; charset=utf-8
  • isDeprecated boolean | null nullable

    Whether the Actor is deprecated.

Status 201

Response Headers
  • Location 
{
  "data": {
    "id": "zdc3Pyhyz3m8vjDeM",
    "userId": "wRsJZtadYvn4mBZmm",
    "name": "MyActor",
    "username": "jane35",
    "description": "My favourite Actor!",
    "isPublic": false,
    "createdAt": "2019-07-08T11:27:57.401Z",
    "modifiedAt": "2019-07-08T14:01:05.546Z",
    "stats": {
      "totalBuilds": 9,
      "totalRuns": 16,
      "totalUsers": 6,
      "totalUsers7Days": 2,
      "totalUsers30Days": 6,
      "totalUsers90Days": 6,
      "totalMetamorphs": 2,
      "lastRunStartedAt": "2019-07-08T14:01:05.546Z"
    },
    "versions": [
      {
        "versionNumber": "0.1",
        "envVars": null,
        "sourceType": "SOURCE_FILES",
        "applyEnvVarsToBuild": false,
        "buildTag": "latest",
        "sourceFiles": []
      },
      {
        "versionNumber": "0.2",
        "sourceType": "GIT_REPO",
        "envVars": null,
        "applyEnvVarsToBuild": false,
        "buildTag": "latest",
        "gitRepoUrl": "https://github.com/jane35/my-actor"
      },
      {
        "versionNumber": "0.3",
        "sourceType": "TARBALL",
        "envVars": null,
        "applyEnvVarsToBuild": false,
        "buildTag": "latest",
        "tarballUrl": "https://github.com/jane35/my-actor/archive/master.zip"
      },
      {
        "versionNumber": "0.4",
        "sourceType": "GITHUB_GIST",
        "envVars": null,
        "applyEnvVarsToBuild": false,
        "buildTag": "latest",
        "gitHubGistUrl": "https://gist.github.com/jane35/e51feb784yu89"
      }
    ],
    "defaultRunOptions": {
      "build": "latest",
      "timeoutSecs": 3600,
      "memoryMbytes": 2048,
      "restartOnError": false
    },
    "exampleRunInput": {
      "body": "{ \"helloWorld\": 123 }",
      "contentType": "application/json; charset=utf-8"
    },
    "isDeprecated": false,
    "deploymentKey": "ssh-rsa AAAA ...",
    "title": "My Actor",
    "taggedBuilds": {
      "latest": {
        "buildId": "z2EryhbfhgSyqj6Hn",
        "buildNumber": "0.0.2",
        "finishedAt": "2019-06-10T11:15:49.286Z"
      }
    }
  }
}