Actors

Creates an Actor with the settings specified in an Actor object passed as JSON in the POST payload.

Returns the created Actor object.

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.

Publish an Actor

To make your Actor public, use the Update Actor endpoint.

post/v2/actors

Request

  • Base URL
    https://api.apify.com
  • Auth
    • HTTP bearer
    • or API key in query parameter token

Request body

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

descriptionstring nullable

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

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

isPublicboolean

Whether the Actor is available to users in Apify Store. A new Actor is always private. To publish it, build it first, then update it with isPublic set to true.

actorPermissionLevel'LIMITED_PERMISSIONS' | 'FULL_PERMISSIONS'

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

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

seoDescriptionstring nullable

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

restartOnErrorboolean
categoriesstring[] nullable

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

isDeprecatedboolean nullable

Whether the Actor is deprecated.

Example request

{
  "name": "instagram-scraper",
  "description": "This scraper extracts posts and comments from Instagram.",
  "title": "Instagram scraper",
  "actorPermissionLevel": "LIMITED_PERMISSIONS",
  "seoTitle": "Free Instagram scraper",
  "seoDescription": "The best scraper for Instagram",
  "versions": [
    {
      "versionNumber": "1.6",
      "envVars": [
        {
          "name": "MY_ENV_VAR",
          "value": "my-value"
        }
      ],
      "buildTag": "latest",
      "sourceFiles": [
        {
          "format": "TEXT",
          "content": "console.log('This is the main.js file');",
          "name": "src/main.js"
        }
      ]
    }
  ],
  "categories": [
    "SOCIAL_MEDIA"
  ],
  "defaultRunOptions": {
    "build": "latest",
    "timeoutSecs": 3600,
    "memoryMbytes": 2048,
    "maxTotalChargeUsd": 5,
    "forcePermissionLevel": "LIMITED_PERMISSIONS"
  },
  "actorStandby": {
    "tenancy": "SINGLE_TENANT"
  },
  "exampleRunInput": {
    "body": "{ \"helloWorld\": 123 }",
    "contentType": "application/json; charset=utf-8"
  }
}

Response

Example response

{
  "data": {
    "id": "zdc3Pyhyz3m8vjDeM",
    "userId": "wRsJZtadYvn4mBZmm",
    "name": "google-search-extractor",
    "username": "compass",
    "description": "Extract data from hundreds of places fast.",
    "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",
      "actorReviewCount": 69,
      "actorReviewRating": 4.7,
      "bookmarkCount": 1269,
      "publicActorRunStats30Days": {
        "ABORTED": 2542,
        "FAILED": 1234,
        "SUCCEEDED": 732805,
        "TIMED-OUT": 12556,
        "TOTAL": 749137
      }
    },
    "versions": [
      {
        "versionNumber": "0.0",
        "envVars": [
          {
            "name": "MY_ENV_VAR",
            "value": "my-value",
            "valueHash": "a1b2c3"
          }
        ],
        "buildTag": "latest",
        "sourceFiles": [
          {
            "format": "TEXT",
            "content": "console.log('This is the main.js file');",
            "name": "src/main.js"
          }
        ]
      }
    ],
    "pricingInfos": [
      {
        "apifyMarginPercentage": 0.2
      }
    ],
    "defaultRunOptions": {
      "build": "latest",
      "timeoutSecs": 3600,
      "memoryMbytes": 2048,
      "maxTotalChargeUsd": 5,
      "forcePermissionLevel": "LIMITED_PERMISSIONS"
    },
    "exampleRunInput": {
      "body": "{ \"helloWorld\": 123 }",
      "contentType": "application/json; charset=utf-8"
    },
    "deploymentKey": "ssh-rsa AAAA ...",
    "title": "Google Search Extractor",
    "taggedBuilds": {
      "latest": {
        "buildId": "z2EryhbfhgSyqj6Hn",
        "buildNumber": "0.0.2",
        "finishedAt": "2019-06-10T11:15:49.286Z"
      },
      "beta": {
        "buildId": "abc123def456",
        "buildNumber": "1.0.5",
        "finishedAt": "2019-07-15T14:30:00.000Z"
      }
    },
    "actorStandby": {
      "tenancy": "SINGLE_TENANT"
    },
    "seoTitle": "Web Scraper",
    "seoDescription": "Crawls websites using Chrome and extracts data from pages using JavaScript.",
    "pictureUrl": "https://apify-image-uploads-prod.s3.amazonaws.com/.../actor-picture.png",
    "standbyUrl": "https://jane35--my-actor.apify.actor",
    "notice": "UNDER_MAINTENANCE",
    "categories": [
      "DEVELOPER_TOOLS",
      "OPEN_SOURCE"
    ],
    "isSourceCodeHidden": true
  }
}

Changes

    • breaking

      request property // was restricted to a list of enum values

    • warning

      added the new MULTI_TENANT enum value to the /// response property for the response status

    • warning

      added the new SINGLE_TENANT enum value to the /// response property for the response status

    • warning

      added the new undefined enum value to the /// response property for the response status

    • info

      added the new MULTI_TENANT enum value to the request property //

    • info

      added the new SINGLE_TENANT enum value to the request property //

    • info

      added the new undefined enum value to the request property //

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status