Get an App Run

GET/openapi/v1/app-runs/{runId}

GET /openapi/v1/app-runs/{runId}
Authorization: Bearer <API_KEY>

Request parameters

Parameter	Location	Type	Required	Description
`runId`	Path	`string`	Yes	Run ID returned by the creation API

runId is an opaque string returned unchanged by the creation API. Any active Key belonging to the same user can query the Run; other users cannot. Clients must not depend on its length or generation rules.

The success status is HTTP 200.

Success response example

{

"code": 200,

"message": "success",

"data": {

"runId": "e8f4c7a135d64211a8d2c0019b57ef63",

"status": "running",

"progress": 67,

"estimatedPrice": "3.25000000",

"actualPrice": "3.25000000",

"createdAt": 1786759200000,

"endTime": null,

"outputs": [

{

"name": "Final video",

"url": null,

"type": "video"

}

"steps": [

{

"stepIndex": 0,

"nodeKey": "node-character-image",

"nodeType": "image",

"name": "Generate character image",

"estimatedPrice": "1.86040938",

"url": "https://example.com/a.png",

"type": "image",

"status": "succeeded",

"progress": 100,

"actualPrice": "3.25000000"

{

"stepIndex": 1,

"nodeKey": "node-video",

"nodeType": "video",

"name": "Generate video",

"estimatedPrice": "1.38959062",

"url": null,

"type": "video",

"status": "running",

"progress": 34,

"actualPrice": "0.00000000"

}

"error": null

}

integerProtocol field, currently fixed at 200

stringFixed at success when the API query succeeds

objectRun status and results

stringRun ID returned by the creation API

stringRun status; see the enum below

integerOverall progress from 0–100; always 100 in a terminal state

decimal stringApp's estimated Credit price recorded when the Run was created, with exactly 8 decimal places

decimal stringTotal completed Credit charges at query time

integerRun creation time as a Unix timestamp in milliseconds

integer/nullRun completion time as a Unix timestamp in milliseconds; null before completion

arrayFinal outputs declared when the App was published

stringOutput name declared by the publisher

string/nullPublic result URL that requires no additional signature; null until generated

stringOutput type: text, image, video, or audio

arrayPublic execution steps declared when the App was published

integerStable position in this Run's public step list

stringStable identifier associating the step with App details

stringStep type

stringStep display name

decimal stringEstimated Credit price for the step, with exactly 8 decimal places

string/nullPublic URL for the step's primary result; null until generated

stringStep result type: text, image, video, or audio

stringStep status returned by the execution service

integerStep progress from 0–100

decimal stringCompleted Credit charges attributed to the step

integerStable position in this Run's public step list

stringStable identifier associating the step with App details

stringStep type

stringStep display name

decimal stringEstimated Credit price for the step, with exactly 8 decimal places

string/nullPublic URL for the step's primary result; null until generated

stringStep result type: text, image, video, or audio

stringStep status returned by the execution service

integerStep progress from 0–100

decimal stringCompleted Credit charges attributed to the step

object/nullSanitized Run error on failure; null for other states

Run statuses

Status	Terminal	Meaning
`pending`	No	Created and waiting to be submitted to the execution service
`queued`	No	Entered the execution queue
`running`	No	Currently executing
`canceling`	No	Cancellation in progress; v1 has no external cancel API, but platform operations may produce this state
`succeeded`	Yes	All required steps succeeded
`partial_success`	Yes	Some steps succeeded and produced usable results
`failed`	Yes	The Run failed
`canceled`	Yes	The Run was canceled

outputs

outputs contains only outputs declared by the publisher. Array order follows this Run's public output list. Result URLs are public and can be accessed directly without an additional signature.

Text results are also returned through HTTPS file URLs rather than embedded directly in JSON.

steps

stepIndex, nodeKey, nodeType, name, and estimatedPrice come from the step list recorded when this Run was created. Republishing the App later does not change these fields on existing Runs. nodeKey is only used to associate steps.

Before a step starts, it usually returns status=pending and progress=0. A step may produce multiple results; steps[].url shows only its primary result. Use outputs for the complete final results.

Failed Runs

When execution fails, the HTTP status and top-level message still indicate that the query itself succeeded. data.status is failed, and the response includes a sanitized Run error:

Failed response example

{

"code": 200,

"message": "success",

"data": {

"runId": "e8f4c7a135d64211a8d2c0019b57ef63",

"status": "failed",

"progress": 100,

"estimatedPrice": "3.25000000",

"actualPrice": "3.25000000",

"createdAt": 1786759200000,

"endTime": 1786759260000,

"outputs": [],

"steps": [],

"error": {

"code": "RUN_EXECUTION_FAILED",

"message": "Run execution failed"

}

integerProtocol field, currently fixed at 200

stringFixed at success when the API query succeeds

objectStatus and results of the failed Run

stringID of the Run that failed

stringRun status, fixed at failed in this example

integerOverall progress; always 100 in a terminal state

decimal stringApp's estimated Credit price recorded when the Run was created

decimal stringActual Credit charges completed before failure

integerRun creation time as a Unix timestamp in milliseconds

integerRun completion time as a Unix timestamp in milliseconds

arrayFinal outputs produced; empty when no usable result exists

arrayPublic step results; empty in this example

objectSanitized Run execution error

stringRun execution error code

stringRun failure message safe to display

Distinguish between these error types:

The top-level message is not success, and data contains error.code: the API call failed, for example because of authentication, invalid input, or rate limiting.
The top-level message is success, data contains runId/status/..., and data.error is not null: the API query succeeded, but asynchronous Run execution failed.

Code examples

Replace REPLACE_WITH_YOUR_RUN_ID with the Run ID returned by the creation API. The examples below use the MAXDAY_API_KEY environment variable.

curl --fail-with-body \
  "https://api.maxday.ai/bio/dramas/v1/openapi/v1/app-runs/REPLACE_WITH_YOUR_RUN_ID" \
  --header "Authorization: Bearer ${MAXDAY_API_KEY}"

const runId = "REPLACE_WITH_YOUR_RUN_ID";
const response = await fetch(
  `https://api.maxday.ai/bio/dramas/v1/openapi/v1/app-runs/${runId}`,
  {
    headers: {
      Authorization: `Bearer ${process.env.MAXDAY_API_KEY}`,
    },
  },
);
const body = await response.json();

if (!response.ok || body.message !== "success") {
  throw new Error(body.data?.error?.message || body.message || `HTTP ${response.status}`);
}
console.log(body.data);

import json
import os
from urllib.request import Request, urlopen

run_id = "REPLACE_WITH_YOUR_RUN_ID"
request = Request(
    "https://api.maxday.ai/bio/dramas/v1/openapi/v1/app-runs/" + run_id,
    headers={"Authorization": "Bearer " + os.environ["MAXDAY_API_KEY"]},
)

with urlopen(request, timeout=60) as response:
    body = json.load(response)

if body.get("message") != "success":
    error = body.get("data", {}).get("error", {})
    raise RuntimeError(error.get("message") or body.get("message"))
print(json.dumps(body["data"], ensure_ascii=False, indent=2))

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public final class GetAppRunExample {
  public static void main(String[] args) throws Exception {
    String runId = "REPLACE_WITH_YOUR_RUN_ID";
    ObjectMapper json = new ObjectMapper();
    HttpRequest request = HttpRequest.newBuilder(
            URI.create("https://api.maxday.ai/bio/dramas/v1/openapi/v1/app-runs/" + runId))
        .header("Authorization", "Bearer " + System.getenv("MAXDAY_API_KEY"))
        .GET()
        .build();
    HttpResponse<String> response = HttpClient.newHttpClient().send(
        request,
        HttpResponse.BodyHandlers.ofString()
    );
    JsonNode body = json.readTree(response.body());

    if (response.statusCode() < 200 || response.statusCode() >= 300
        || !"success".equals(body.path("message").asText())) {
      throw new IllegalStateException(
          body.path("data").path("error").path("message").asText(
              body.path("message").asText("HTTP " + response.statusCode())
          )
      );
    }
    System.out.println(body.path("data").toPrettyString());
  }
}