Run Actor

POST 
/v2/acts/: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 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 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 API endpoint.

Request

Path Parameters

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

Example: janedoe~my-actor

Query Parameters

timeout double
Optional timeout for the run, in seconds. By default, the run uses a timeout specified in the default run configuration for the Actor.

Example: 60
memory double
Memory limit for the run, in megabytes. The amount of memory can be set to a power of 2 with a minimum of 128. By default, the run uses a memory limit specified in the default run configuration for the Actor.

Example: 256
maxItems double
Specifies the maximum number of dataset items that will be charged for pay-per-result Actors. This does NOT guarantee that the Actor will return only this many items. It only ensures you won't be charged for more than this number of items. Only works for pay-per-result Actors. Value can be accessed in the actor run using ACTOR_MAX_PAID_DATASET_ITEMS environment variable.

Example: 1000
maxTotalChargeUsd double
Specifies the maximum cost of the run. This parameter is useful for pay-per-event Actors, as it allows you to limit the amount charged to your subscription. You can access the maximum cost in your Actor by using the ACTOR_MAX_TOTAL_CHARGE_USD environment variable.

Example: 5
restartOnError boolean
Determines whether the run will be restarted if it fails.

Example: false
build string
Specifies the Actor build to run. It can be either a build tag or build number. By default, the run uses the build specified in the default run configuration for the Actor (typically latest).

Example: 0.1.234
waitForFinish double
The maximum number of seconds the server waits for the run to finish. By default, it is 0, the maximum value is 60. If the run finishes in time then the returned run object will have a terminal status (e.g. SUCCEEDED), otherwise it will have a transitional status (e.g. RUNNING).

Example: 60
webhooks string
Specifies optional webhooks associated with the Actor run, which can be used to receive a notification e.g. when the Actor finished or failed. The value is a Base64-encoded JSON array of objects defining the webhooks. For more information, see Webhooks documentation.

Example: dGhpcyBpcyBqdXN0IGV4YW1wbGUK...
forcePermissionLevel string
Possible values: [LIMITED_PERMISSIONS, FULL_PERMISSIONS]
Overrides the Actor's permission level for this specific run. Use to test restricted permissions before deploying changes to your Actor or to temporarily elevate or restrict access. If you don't specify this parameter, the Actor uses its configured default permission level. For more information on permissions, see the documentation.

Example: LIMITED_PERMISSIONS

Bodyrequired

• object object

Status 201

Response Headers

• Location

{
  "data": {
    "id": "HG7ML7M8z78YcAPEB",
    "actId": "HDSasDasz78YcAPEB",
    "userId": "7sT5jcggjjA9fNcxF",
    "actorTaskId": "KJHSKHausidyaJKHs",
    "startedAt": "2019-11-30T07:34:24.202Z",
    "finishedAt": "2019-12-12T09:30:12.202Z",
    "status": "RUNNING",
    "statusMessage": "Actor is running",
    "isStatusMessageTerminal": false,
    "meta": {
      "origin": "WEB",
      "clientIp": "172.234.12.34",
      "userAgent": "Mozilla/5.0 (iPad)"
    },
    "stats": {
      "inputBodyLen": 240,
      "migrationCount": 0,
      "restartCount": 0,
      "resurrectCount": 2,
      "memAvgBytes": 267874071.9,
      "memMaxBytes": 404713472,
      "memCurrentBytes": 0,
      "cpuAvgUsage": 33.75321011075384,
      "cpuMaxUsage": 169.65073553494125,
      "cpuCurrentUsage": 0,
      "netRxBytes": 103508042,
      "netTxBytes": 4854600,
      "durationMillis": 248472,
      "runTimeSecs": 248.472,
      "metamorph": 0,
      "computeUnits": 0.13804
    },
    "options": {
      "build": "latest",
      "timeoutSecs": 300,
      "memoryMbytes": 1024,
      "diskMbytes": 2048
    },
    "buildId": "7sT5jcggjjA9fNcxF",
    "exitCode": 0,
    "generalAccess": "RESTRICTED",
    "defaultKeyValueStoreId": "eJNzqsbPiopwJcgGQ",
    "defaultDatasetId": "wmKPijuyDnPZAPRMk",
    "defaultRequestQueueId": "FL35cSF7jrxr3BY39",
    "buildNumber": "0.0.36",
    "containerUrl": "https://g8kd8kbc5ge8.runs.apify.net",
    "isContainerServerReady": true,
    "gitBranchName": "master",
    "usage": {
      "ACTOR_COMPUTE_UNITS": 3,
      "DATASET_READS": 4,
      "DATASET_WRITES": 4,
      "KEY_VALUE_STORE_READS": 5,
      "KEY_VALUE_STORE_WRITES": 3,
      "KEY_VALUE_STORE_LISTS": 5,
      "REQUEST_QUEUE_READS": 2,
      "REQUEST_QUEUE_WRITES": 1,
      "DATA_TRANSFER_INTERNAL_GBYTES": 1,
      "DATA_TRANSFER_EXTERNAL_GBYTES?": 3,
      "PROXY_RESIDENTIAL_TRANSFER_GBYTES": 34,
      "PROXY_SERPS": 3
    },
    "usageTotalUsd": 0.2654,
    "usageUsd": {
      "ACTOR_COMPUTE_UNITS": 0.072,
      "DATASET_READS": 0.0004,
      "DATASET_WRITES": 0.0002,
      "KEY_VALUE_STORE_READS": 0.0006,
      "KEY_VALUE_STORE_WRITES": 0.002,
      "KEY_VALUE_STORE_LISTS": 0.004,
      "REQUEST_QUEUE_READS": 0.005,
      "REQUEST_QUEUE_WRITES": 0.02,
      "DATA_TRANSFER_INTERNAL_GBYTES": 0.0004,
      "DATA_TRANSFER_EXTERNAL_GBYTES?": 0.0002,
      "PROXY_RESIDENTIAL_TRANSFER_GBYTES": 0.16,
      "PROXY_SERPS": 0.0006
    }
  }
}

Schema

• data object required

  Represents an Actor run and its associated data.

  • id string required

    Unique identifier of the Actor run.

    
    Example: HG7ML7M8z78YcAPEB
  • actId string required

    ID of the Actor that was run.

    
    Example: HDSasDasz78YcAPEB
  • userId string required

    ID of the user who started the run.

    
    Example: 7sT5jcggjjA9fNcxF
  • actorTaskId string | null nullable

    ID of the Actor task, if the run was started from a task.

    
    Example: KJHSKHausidyaJKHs
  • startedAt string<date-time> required

    Time when the Actor run started.

    
    Example: 2019-11-30T07:34:24.202Z
  • finishedAt string,null<date-time> nullable

    Time when the Actor run finished.

    
    Example: 2019-12-12T09:30:12.202Z
  • status ActorJobStatus (string) required

    Status of an Actor job (run or build).

    Possible values: [READY, RUNNING, SUCCEEDED, FAILED, TIMING-OUT, TIMED-OUT, ABORTING, ABORTED]

  • statusMessage string | null nullable

    Detailed message about the run status.

    
    Example: Actor is running
  • isStatusMessageTerminal boolean | null nullable

    Whether the status message is terminal (final).

    
    Example: false
  • meta object required

    Metadata about the Actor run.

    • origin RunOrigin (string) required

      Possible values: [DEVELOPMENT, WEB, API, SCHEDULER, TEST, WEBHOOK, ACTOR, CLI, STANDBY]

    • clientIp string | null nullable

      IP address of the client that started the run.

    • userAgent string | null nullable

      User agent of the client that started the run.

    • scheduleId string | null nullable

      ID of the schedule that triggered the run.

    • scheduledAt string,null<date-time> nullable

      Time when the run was scheduled.

  • pricingInfo object

    Pricing information for the Actor.

    pricingModel
    Pricing information for the Actor.
    Possible values: [PAY_PER_EVENT, PRICE_PER_DATASET_ITEM, FLAT_PRICE_PER_MONTH, FREE]
    • PAY_PER_EVENT
      • 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
      • pricingPerEvent object required

        • actorChargeEvents object

          • property name* ActorChargeEvent

            • eventPriceUsd number required
            • eventTitle string required
            • eventDescription string required
      • minimalMaxTotalChargeUsd number | null nullable
    • PRICE_PER_DATASET_ITEM
      • 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
      • unitName string required

        Name of the unit that is being charged

      • pricePerUnitUsd number required
    • FLAT_PRICE_PER_MONTH
      • 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
      • trialMinutes integer required

        For how long this Actor can be used for free in trial period

      • pricePerUnitUsd number required

        Monthly flat price in USD

    • FREE
      • 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
  • stats object required

    Statistics of the Actor run.

    • inputBodyLen integer

      Possible values: >= 0

      
      Example: 240
    • migrationCount integer

      Possible values: >= 0

      
      Example: 0
    • rebootCount integer

      Possible values: >= 0

      
      Example: 0
    • restartCount integer required

      Possible values: >= 0

      
      Example: 0
    • resurrectCount integer required

      Possible values: >= 0

      
      Example: 2
    • memAvgBytes number
      Example: 267874071.9
    • memMaxBytes integer

      Possible values: >= 0

      
      Example: 404713472
    • memCurrentBytes integer

      Possible values: >= 0

      
      Example: 0
    • cpuAvgUsage number
      Example: 33.7532101107538
    • cpuMaxUsage number
      Example: 169.650735534941
    • cpuCurrentUsage number
      Example: 0
    • netRxBytes integer

      Possible values: >= 0

      
      Example: 103508042
    • netTxBytes integer

      Possible values: >= 0

      
      Example: 4854600
    • durationMillis integer

      Possible values: >= 0

      
      Example: 248472
    • runTimeSecs number

      Possible values: >= 0

      
      Example: 248.472
    • metamorph integer

      Possible values: >= 0

      
      Example: 0
    • computeUnits number required

      Possible values: >= 0

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

    • property name* integer
  • options object required

    Configuration options for the Actor run.

    • build string required
      Example: latest
    • timeoutSecs integer required

      Possible values: >= 0

      
      Example: 300
    • memoryMbytes integer required

      Possible values: >= 128 and <= 32768

      
      Example: 1024
    • diskMbytes integer required

      Possible values: >= 0

      
      Example: 2048
    • maxItems integer

      Possible values: >= 1

      
      Example: 1000
    • maxTotalChargeUsd number

      Possible values: >= 0

      
      Example: 5
  • buildId string required

    ID of the Actor build used for this run.

    
    Example: 7sT5jcggjjA9fNcxF
  • exitCode integer | null nullable

    Exit code of the Actor run process.

    
    Example: 0
  • generalAccess GeneralAccessEnum (string) required

    General access level for the Actor run.

    Possible values: [ANYONE_WITH_ID_CAN_READ, ANYONE_WITH_NAME_CAN_READ, FOLLOW_USER_SETTING, RESTRICTED]

    
    Example: RESTRICTED
  • defaultKeyValueStoreId string required

    ID of the default key-value store for this run.

    
    Example: eJNzqsbPiopwJcgGQ
  • defaultDatasetId string required

    ID of the default dataset for this run.

    
    Example: wmKPijuyDnPZAPRMk
  • defaultRequestQueueId string required

    ID of the default request queue for this run.

    
    Example: FL35cSF7jrxr3BY39
  • buildNumber string

    Build number of the Actor build used for this run.

    
    Example: 0.0.36
  • containerUrl string<uri>

    URL of the container running the Actor.

    
    Example: https://g8kd8kbc5ge8.runs.apify.net
  • isContainerServerReady boolean | null nullable

    Whether the container's HTTP server is ready to accept requests.

    
    Example: true
  • gitBranchName string | null nullable

    Name of the git branch used for the Actor build.

    
    Example: master
  • usage object

    Resource usage statistics for the run.

    anyOf
    • RunUsage
    • null
    ACTOR_COMPUTE_UNITS number | null nullable
    Example: 3
    DATASET_READS integer | null nullable
    Example: 4
    DATASET_WRITES integer | null nullable
    Example: 4
    KEY_VALUE_STORE_READS integer | null nullable
    Example: 5
    KEY_VALUE_STORE_WRITES integer | null nullable
    Example: 3
    KEY_VALUE_STORE_LISTS integer | null nullable
    Example: 5
    REQUEST_QUEUE_READS integer | null nullable
    Example: 2
    REQUEST_QUEUE_WRITES integer | null nullable
    Example: 1
    DATA_TRANSFER_INTERNAL_GBYTES number | null nullable
    Example: 1
    DATA_TRANSFER_EXTERNAL_GBYTES? number | null nullable
    Example: 3
    PROXY_RESIDENTIAL_TRANSFER_GBYTES number | null nullable
    Example: 34
    PROXY_SERPS integer | null nullable
    Example: 3
  • usageTotalUsd number | null 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). Not available for Pay-Per-Result Actors when you're not the Actor owner.

    
    Example: 0.2654
  • usageUsd object

    Platform usage costs breakdown in USD. Only present if you own the run AND are paying for platform usage (Pay-Per-Usage, Rental, or Pay-Per-Event with usage costs like standby Actors). Not available for standard Pay-Per-Event Actors or Pay-Per-Result Actors owned by others.

    anyOf
    • RunUsageUsd
    • null
    ACTOR_COMPUTE_UNITS number | null nullable
    Example: 0.0003
    DATASET_READS number | null nullable
    Example: 0.0001
    DATASET_WRITES number | null nullable
    Example: 0.0001
    KEY_VALUE_STORE_READS number | null nullable
    Example: 0.0001
    KEY_VALUE_STORE_WRITES number | null nullable
    Example: 0.00005
    KEY_VALUE_STORE_LISTS number | null nullable
    Example: 0.0001
    REQUEST_QUEUE_READS number | null nullable
    Example: 0.0001
    REQUEST_QUEUE_WRITES number | null nullable
    Example: 0.0001
    DATA_TRANSFER_INTERNAL_GBYTES number | null nullable
    Example: 0.001
    DATA_TRANSFER_EXTERNAL_GBYTES? number | null nullable
    Example: 0.003
    PROXY_RESIDENTIAL_TRANSFER_GBYTES number | null nullable
    Example: 0.034
    PROXY_SERPS number | null nullable
    Example: 0.003
  • metamorphs object

    List of metamorph events that occurred during the run.

    anyOf
    • object[]
    • null
    createdAt string<date-time> required
    Time when the metamorph occurred.
    
    Example: 2019-11-30T07:39:24.202Z
    actorId string required
    ID of the Actor that the run was metamorphed to.
    
    Example: nspoEjklmnsF2oosD
    buildId string required
    ID of the build used for the metamorphed Actor.
    
    Example: ME6oKecqy5kXDS4KQ
    inputKey string | null nullable
    Key of the input record in the key-value store.
    
    Example: INPUT-METAMORPH-1

Status 400

Bad request - invalid input parameters or request body.

{
  "error": {
    "type": "invalid-input",
    "message": "Invalid input: The request body contains invalid data."
  }
}

Schema

• error object required

  • type string required
    Example: run-failed
  • message string required
    Example: Actor run did not succeed (run ID: 55uatRrZib4xbZs, status: FAILED)