Metamorph run

POST 
/v2/actor-runs/:runId/metamorph

Transforms an Actor run into a run of another Actor with a new input.

This is useful if you want to use another Actor to finish the work of your current Actor run, without the need to create a completely new run and waiting for its finish.

For the users of your Actors, the metamorph operation is transparent, they will just see your Actor got the work done.

Internally, the system stops the Docker container corresponding to the Actor run and starts a new container using a different Docker image.

All the default storages are preserved and the new input is stored under the INPUT-METAMORPH-1 key in the same default key-value store.

For more information, see the Actor docs.

Request

Path Parameters

runId string required
Actor run ID.

Example: 3KH8gEpp4d8uQSe8T

Query Parameters

targetActorId string required
ID of a target Actor that the run should be transformed into.

Example: HDSasDasz78YcAPEB
build string
Optional build of the target Actor.
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 target Actor (typically latest).

Example: beta

Status 200

Response Headers

{
  "data": {
    "id": "HG7ML7M8z78YcAPEB",
    "actId": "janedoe~my-actor",
    "userId": "PNWZBd7Z9c746JAnF",
    "startedAt": "2019-11-30T07:34:24.202Z",
    "finishedAt": null,
    "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": 1,
      "memAvgBytes": 35914228.4,
      "memMaxBytes": 38244352,
      "memCurrentBytes": 0,
      "cpuAvgUsage": 0.00955965,
      "cpuMaxUsage": 3.1546,
      "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": "HG7ML7M8z78YcAPEB",
    "exitCode": 0,
    "generalAccess": "RESTRICTED",
    "defaultKeyValueStoreId": "eJNzqsbPiopwJcgGQ",
    "defaultDatasetId": "wmKPijuyDnPZAPRMk",
    "defaultRequestQueueId": "FL35cSF7jrxr3BY39",
    "metamorphs": [
      {
        "createdAt": "2019-11-30T07:39:24.202Z",
        "actorId": "nspoEjklmnsF2oosD",
        "buildId": "ME6oKecqy5kXDS4KQ",
        "inputKey": "INPUT-METAMORPH-1"
      }
    ],
    "buildNumber": "0.1.10",
    "containerUrl": "https://hfewsyknno9o.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
    }
  }
}

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)