Skip to main content

Update Actor

PUT 
/v2/actors/:actorId

Updates an Actor's settings with the values specified in an Actor object passed as JSON in the POST payload. Only the fields specified in the request body are updated.

Returns the full Actor object, the same as the Get Actor endpoint.

In the HTTP request, set the Content-Type header to application/json.

Authentication

To provide the authentication token, we recommend using the request's Authorization header, rather than the URL. For details, see Authentication.

Make an Actor public

To make your Actor public:

Update build tags

To change tags assigned to Actor builds, use the taggedBuilds object. It's a dictionary that maps tag names to specific builds, where:

  • the key is the tag name, for example latest or beta
  • the value is either null or an object with a build ID

Changing tags is a patch operation. Only the tags that you provide in this object are updated.

Note that you can assign multiple tags to a single build, but you can't assign the same tag to multiple builds.

  • To create or reassign a tag, provide the tag name with a build ID. For example, to assign the latest tag to a build, use:
{
  "latest": { "buildId": "z2EryhbfhgSyqj6Hn" }
}
  • To remove a tag from a build, provide the tag name with a null value. For example, to remove the beta tag, use:
{
  "beta": null
}
  • You can perform multiple actions at once. The following example reassigns latest and removes beta, while preserving other existing tags:
{
  "latest": { "buildId": "z2EryhbfhgSyqj6Hn" },
  "beta": null
}

Request

Path Parameters

    actorId string required

    Actor ID or a tilde-separated owner's username and Actor name.


    Example: janedoe~my-actor

Bodyrequired

  • name string

    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.
  • isPublic boolean

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


    Example: false
  • actorPermissionLevel 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
  • 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
  • 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
  • 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.

    • versionNumber string | null nullable

      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: 1.6
    • sourceType object

      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 of the tarball to download the source code from. 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 by the user.

      anyOf
    • 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
  • taggedBuilds object,null

    A dictionary that maps tag names to specific builds. For details, see Update build tags.

    • property name* BuildTag

      The name of the build tag.

      • buildId string required

        The ID of the build to assign to the tag.

  • 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 200

Response Headers
    {
      "data": {
        "id": "zdc3Pyhyz3m8vjDeM",
        "userId": "wRsJZtadYvn4mBZmm",
        "name": "MyActor",
        "username": "jane35",
        "description": "My favourite Actor!",
        "isPublic": false,
        "actorPermissionLevel": "LIMITED_PERMISSIONS",
        "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"
          }
        }
      }
    }