Get list of runs

GET /v2/acts/:actorId/runs

Gets the list of runs of a specific Actor. The response is a list of objects, where each object contains basic information about a single Actor run.

The endpoint supports pagination using the limit and offset parameters and it will not return more than 1000 array elements.

By default, the records are sorted by the startedAt field in ascending order, therefore you can use pagination to incrementally fetch all records while new ones are still being created. To sort the records in descending order, use desc=1 parameter. You can also filter runs by status (available statuses).

Request

Path Parameters

actorId string required

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

Example: janedoe~my-actor

Query Parameters

offset double

Number of array elements that should be skipped at the start. The default value is 0.

Example: 10

limit double

Maximum number of array elements to return. The default value as well as the maximum is 1000.

Example: 99

desc boolean

If true or 1 then the objects are sorted by the startedAt field in descending order. By default, they are sorted in ascending order.

Example: true

status string

Single status or comma-separated list of statuses, see (available statuses). Used to filter runs by the specified statuses only.

Example: SUCCEEDED

startedAfter date-time

Filter runs that started after the specified date and time (inclusive). The value must be a valid ISO 8601 datetime string (UTC).

Example: 2025-09-01T00:00:00.000Z

startedBefore date-time

Filter runs that started before the specified date and time (inclusive). The value must be a valid ISO 8601 datetime string (UTC).

Example: 2025-09-17T23:59:59.000Z

Status 200

Response Headers

{
  "data": {
    "total": 2,
    "offset": 0,
    "limit": 1000,
    "desc": false,
    "count": 2,
    "items": [
      {
        "id": "HG7ML7M8z78YcAPEB",
        "actId": "HDSasDasz78YcAPEB",
        "actorTaskId": "KJHSKHausidyaJKHs",
        "status": "SUCCEEDED",
        "startedAt": "2019-11-30T07:34:24.202Z",
        "finishedAt": "2019-12-12T09:30:12.202Z",
        "buildId": "HG7ML7M8z78YcAPEB",
        "buildNumber": "0.0.2",
        "meta": {
          "origin": "WEB"
        },
        "usageTotalUsd": 0.2,
        "defaultKeyValueStoreId": "sfAjeR4QmeJCQzTfe",
        "defaultDatasetId": "3ZojQDdFTsyE7Moy4",
        "defaultRequestQueueId": "so93g2shcDzK3pA85"
      },
      {
        "id": "HG7ML7M8z78YcAPEB",
        "actId": "HDSasDasz78YcAPEB",
        "actorTaskId": "KJHSKHausidyaJKHs",
        "status": "FAILED",
        "startedAt": "2019-12-12T07:34:14.202Z",
        "finishedAt": "2019-12-13T08:36:13.202Z",
        "buildId": "u78dML7M8z78YcAPEB",
        "buildNumber": "0.2.2",
        "meta": {
          "origin": "DEVELOPMENT"
        },
        "usageTotalUsd": 0.6,
        "defaultKeyValueStoreId": "sffsouqlseJCQzTfe",
        "defaultDatasetId": "CFGggdjQDsyE7Moyw",
        "defaultRequestQueueId": "soowucklrmDzKpA8x"
      }
    ]
  }
}

Schema

data object required
Common pagination fields for list responses.
- total integer required
  The total number of items available across all pages.
  Possible values: >= 0
  
  Example: 2
- offset integer required
  The starting position for this page of results.
  Possible values: >= 0
  
  Example: 0
- limit integer required
  The maximum number of items returned per page.
  Possible values: >= 1
  
  Example: 1000
- desc boolean required
  Whether the results are sorted in descending order.
  
  Example: false
- count integer required
  The number of items returned in this response.
  Possible values: >= 0
  
  Example: 2
- items object[] required
  id string required
  Example: HG7ML7M8z78YcAPEB
  actId string required
  Example: HDSasDasz78YcAPEB
  actorTaskId string | null nullable
  Example: KJHSKHausidyaJKHs
  status ActorJobStatus (string) required
  Status of an Actor job (run or build).
  Possible values: [READY, RUNNING, SUCCEEDED, FAILED, TIMING-OUT, TIMED-OUT, ABORTING, ABORTED]
  startedAt string<date-time> required
  Example: 2019-11-30T07:34:24.202Z
  finishedAt string<date-time> required
  Example: 2019-12-12T09:30:12.202Z
  buildId string required
  Example: HG7ML7M8z78YcAPEB
  buildNumber string
  Example: 0.0.2
  meta object required
  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.
  usageTotalUsd number required
  Example: 0.2
  defaultKeyValueStoreId string required
  Example: sfAjeR4QmeJCQzTfe
  defaultDatasetId string required
  Example: 3ZojQDdFTsyE7Moy4
  defaultRequestQueueId string required
  Example: so93g2shcDzK3pA85

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)