acts@{actorId}@runs.yaml

get:
  tags:
    - Actors/Actor runs
  summary: Get list of runs
  description: |
    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)).
  operationId: act_runs_get
  parameters:
    - name: actorId
      in: path
      description: Actor ID or a tilde-separated owner's username and Actor name.
      required: true
      style: simple
      schema:
        type: string
        example: janedoe~my-actor
    - name: offset
      in: query
      description: |
        Number of array elements that should be skipped at the start. The
        default value is `0`.
      style: form
      explode: true
      schema:
        type: number
        format: double
        example: 10
    - name: limit
      in: query
      description: |
        Maximum number of array elements to return. The default value as well as
        the maximum is `1000`.
      style: form
      explode: true
      schema:
        type: number
        format: double
        example: 99
    - name: desc
      in: query
      description: |
        If `true` or `1` then the objects are sorted by the `startedAt` field in
        descending order. By default, they are sorted in ascending order.
      style: form
      explode: true
      schema:
        anyOf:
          - type: boolean
          - type: integer
            enum: [0, 1]
        example: true
    - name: status
      in: query
      description: |
        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.
      style: form
      explode: true
      schema:
        type: string
        example: SUCCEEDED
    - name: startedAfter
      in: query
      description: |
        Filter runs that started after the specified date and time (inclusive).
        The value must be a valid ISO 8601 datetime string (UTC).
      style: form
      explode: true
      schema:
        type: string
        format: date-time
        example: "2025-09-01T00:00:00.000Z"
    - name: startedBefore
      in: query
      description: |
        Filter runs that started before the specified date and time (inclusive).
        The value must be a valid ISO 8601 datetime string (UTC).
      style: form
      explode: true
      schema:
        type: string
        format: date-time
        example: "2025-09-17T23:59:59.000Z"
  responses:
    "200":
      description: ""
      headers: {}
      content:
        application/json:
          schema:
            $ref: ../../components/schemas/actor-runs/ListOfRunsResponse.yaml
          example:
            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
    "400":
      $ref: ../../components/responses/BadRequest.yaml
    "401":
      $ref: ../../components/responses/Unauthorized.yaml
    "403":
      $ref: ../../components/responses/Forbidden.yaml
    "404":
      $ref: ../../components/responses/NotFound.yaml
  deprecated: false
  x-legacy-doc-urls:
    - https://docs.apify.com/api/v2#/reference/actors/run-collection/get-list-of-runs
    - https://docs.apify.com/api/v2#/reference/actors/get-list-of-runs
    - https://docs.apify.com/api/v2#tag/ActorsRun-collection/operation/act_runs_get
  x-js-parent: RunCollectionClient
  x-js-name: list
  x-js-doc-url: https://docs.apify.com/api/client/js/reference/class/RunCollectionClient#list
  x-py-parent: RunCollectionClientAsync
  x-py-name: list
  x-py-doc-url: https://docs.apify.com/api/client/python/reference/class/RunCollectionClientAsync#list
post:
  tags:
    - Actors/Actor runs
  summary: Run Actor
  description: |
    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](#/reference/actor-runs/run-object-and-its-storages/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](#/reference/actors/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](#/reference/datasets/item-collection/get-items)
    API endpoint.
  operationId: act_runs_post
  parameters:
    - name: actorId
      in: path
      description: Actor ID or a tilde-separated owner's username and Actor name.
      required: true
      style: simple
      schema:
        type: string
        example: janedoe~my-actor
    - name: timeout
      in: query
      description: |
        Optional timeout for the run, in seconds. By default, the run uses a
        timeout specified in the default run configuration for the Actor.
      style: form
      explode: true
      schema:
        type: number
        format: double
        example: 60
    - name: memory
      in: query
      description: |
        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.
      style: form
      explode: true
      schema:
        type: number
        format: double
        example: 256
    - $ref: ../../components/parameters/actor-run-options/maxItems.yaml
    - $ref: ../../components/parameters/actor-run-options/maxTotalChargeUsd.yaml
    - name: restartOnError
      in: query
      description: |
        Determines whether the run will be restarted if it fails.
      style: form
      explode: true
      schema:
        type: boolean
        example: false
    - name: build
      in: query
      description: |
        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`).
      style: form
      explode: true
      schema:
        type: string
        example: 0.1.234
    - name: waitForFinish
      in: query
      description: |
        The maximum number of seconds the server waits for the run to finish. By
        default, it is `0`, the maximum value is `60`. <!-- MAX_ACTOR_JOB_ASYNC_WAIT_SECS -->
        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`).
      style: form
      explode: true
      schema:
        type: number
        format: double
        example: 60
    - name: webhooks
      in: query
      description: |
        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](https://docs.apify.com/platform/integrations/webhooks).
      style: form
      explode: true
      schema:
        type: string
        example: dGhpcyBpcyBqdXN0IGV4YW1wbGUK...
    - name: forcePermissionLevel
      in: query
      description: |
        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](https://docs.apify.com/platform/actors/development/permissions).
      style: form
      explode: true
      schema:
        type: string
        enum:
          - LIMITED_PERMISSIONS
          - FULL_PERMISSIONS
        example: LIMITED_PERMISSIONS
  requestBody:
    description: ""
    content:
      application/json:
        schema:
          type: object
        example:
          foo: bar
      application/x-www-form-urlencoded:
        schema:
          type: object
      text/plain:
        schema:
          type: string
    required: true
  responses:
    "201":
      description: ""
      headers:
        Location:
          content:
            text/plain:
              schema:
                type: string
              example: >-
                https://api.apify.com/v2/acts/zdc3Pyhyz3m8vjDeM/runs/HG7ML7M8z78YcAPEB
      content:
        application/json:
          schema:
            $ref: ../../components/schemas/actor-runs/RunResponse.yaml
          example:
            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
    "400":
      $ref: ../../components/responses/BadRequest.yaml
    "401":
      $ref: ../../components/responses/Unauthorized.yaml
    "402":
      $ref: ../../components/responses/PaymentRequired.yaml
    "403":
      $ref: ../../components/responses/Forbidden.yaml
    "404":
      $ref: ../../components/responses/NotFound.yaml
  deprecated: false
  x-legacy-doc-urls:
    - https://docs.apify.com/api/v2#/reference/actors/run-collection/run-actor
    - https://docs.apify.com/api/v2#/reference/actors/run-actor
    - https://docs.apify.com/api/v2#tag/ActorsRun-collection/operation/act_runs_post
  x-js-parent: ActorClient
  x-js-name: start
  x-js-doc-url: https://docs.apify.com/api/client/js/reference/class/ActorClient#start
  x-py-parent: ActorClientAsync
  x-py-name: call
  x-py-doc-url: https://docs.apify.com/api/client/python/reference/class/ActorClientAsync#call