Skip to main content

Run task

POST 
/v2/actor-tasks/:actorTaskId/runs

Runs an Actor task and immediately returns without waiting for the run to finish.

Optionally, you can override the Actor input configuration by passing a JSON object as the POST payload and setting the Content-Type: application/json HTTP header.

Note that if the object in the POST payload does not define a particular input property, the Actor run uses the default value defined by the task (or Actor's input schema if not defined by the task).

The response is the Actor Run object as returned by the Get run endpoint.

If you want to wait for the run to finish and receive the actual output of the Actor run as the response, use one of the Run task 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

    actorTaskId string required

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


    Example: janedoe~my-task

Query Parameters

    timeout double

    Optional timeout for the run, in seconds. By default, the run uses a timeout specified in the task settings.


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


    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 task settings (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.

    Note: if you already have a webhook set up for the Actor or task, you do not have to add it again here.

    For more information, see Webhooks documentation.


    Example: dGhpcyBpcyBqdXN0IGV4YW1wbGUK...

Bodyrequired

  • object object

Status 201

Response Headers
  • Location 
{
  "data": {
    "id": "HG7ML7M8z78YcAPEB",
    "actId": "HDSasDasz78YcAPEB",
    "userId": "BPWZBd9V9c746JAnF",
    "actorTaskId": "KJHSKHausidyaJKHs",
    "startedAt": "2019-11-30T07:34:24.202Z",
    "finishedAt": "2019-12-12T09:30:12.202Z",
    "status": "SUCCEEDED",
    "statusMessage": "Actor has finished",
    "isStatusMessageTerminal": true,
    "meta": {
      "origin": "WEB",
      "clientIp": "172.234.12.34",
      "userAgent": "Mozilla/5.0 (iPad)",
      "scheduleId": "dWazFsPpxMigMSqHL",
      "scheduledAt": "2019-06-10T11:40:00.000Z"
    },
    "stats": {
      "inputBodyLen": 240,
      "migrationCount": 0,
      "restartCount": 0,
      "resurrectCount": 2,
      "memAvgBytes": 35914228.4,
      "memMaxBytes": 38244352,
      "memCurrentBytes": 0,
      "cpuAvgUsage": 0.00955965,
      "cpuMaxUsage": 3.15469,
      "cpuCurrentUsage": 0,
      "netRxBytes": 2652,
      "netTxBytes": 1338,
      "durationMillis": 26239,
      "runTimeSecs": 26.239,
      "metamorph": 0,
      "computeUnits": 0.0072886
    },
    "options": {
      "build": "latest",
      "timeoutSecs": 300,
      "memoryMbytes": 1024,
      "diskMbytes": 2048
    },
    "buildId": "7sT5jcggjjA9fNcxF",
    "exitCode": 0,
    "generalAccess": "RESTRICTED",
    "defaultKeyValueStoreId": "eJNzqsbPiopwJcgGQ",
    "defaultDatasetId": "wmKPijuyDnPZAPRMk",
    "defaultRequestQueueId": "FL35cSF7jrxr3BY39",
    "buildNumber": "0.2.2",
    "containerUrl": "https://nwfcc4btrgqt.runs.apify.com",
    "isContainerServerReady": false,
    "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
    }
  }
}