# Get list of runs ``` GET https://api.apify.com/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](https://docs.apify.com/platform/actors/running/runs-and-builds#lifecycle)). ## 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 items that should be skipped at the start. The default value is `0`. **Example:** `0` **limit** double Maximum number of items to return. The default value as well as the maximum is `1000`. **Example:** `1000` **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](https://docs.apify.com/platform/actors/running/runs-and-builds#lifecycle)). 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:** `1` * **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:** `1` * **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\ required\ **Example:** `2019-11-30T07:34:24.202Z` * **finishedAt** string,null\ nullable\ **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\ 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)` ### Status 401 Unauthorized - authentication required or invalid token. ``` { "error": { "type": "token-not-valid", "message": "Authentication token is not valid." } } ``` **Schema** * **error** object required * **type** string required\ **Example:** `run-failed` * **message** string required\ **Example:** `Actor run did not succeed (run ID: 55uatRrZib4xbZs, status: FAILED)` ### Status 403 Forbidden - insufficient permissions to perform this action. ``` { "error": { "type": "permission-denied", "message": "You do not have permission to perform this action." } } ``` **Schema** * **error** object required * **type** string required\ **Example:** `run-failed` * **message** string required\ **Example:** `Actor run did not succeed (run ID: 55uatRrZib4xbZs, status: FAILED)` ### Status 404 Not found - the requested resource was not found. ``` { "error": { "type": "actor-not-found", "message": "Actor was not found" } } ``` **Schema** * **error** object * **type** string **Possible values:** \[`actor-not-found`] * **message** string\ **Example:** `Actor was not found` ### Status 405 Method not allowed. ``` { "error": { "type": "method-not-allowed", "message": "This API end-point can only be accessed using the following HTTP methods: OPTIONS,GET" } } ``` **Schema** * **error** object required * **type** string required\ **Example:** `run-failed` * **message** string required\ **Example:** `Actor run did not succeed (run ID: 55uatRrZib4xbZs, status: FAILED)` ### Status 429 Too many requests - rate limit exceeded. ``` { "error": { "type": "rate-limit-exceeded", "message": "You have exceeded the rate limit. Please try again later." } } ``` **Schema** * **error** object required * **type** string required\ **Example:** `run-failed` * **message** string required\ **Example:** `Actor run did not succeed (run ID: 55uatRrZib4xbZs, status: FAILED)`