Skip to main content
POST
実行を開始
POST https://api-datahub.octoparse.com/v1/data-apps/{app_id}/runs Authentication: API key required (Authorization: Bearer <API Key>). The request body is one instance of the app input contract (input_schema from app detail). Validation is strict. wait controls whether this call waits for a result:
  • Omitted: follow the app execution.mode default. sync apps wait until a terminal state (capped by the app execution.timeout_seconds); async apps return a run_id immediately.
  • Explicit 0–60: both modes behave the same and wait at most wait seconds. wait=0 returns as soon as the run is queued. For a sync app you can take the run_id first, then long-poll with Get a run wait.
When the response already reaches a terminal state, sample_records may include the first batch. Page the full result with Get run records. version pins the run to a historical release (contract and pricing follow that version). build is for author debugging: it pins an immutable build snapshot (run_kind=test, excluded from public stats, still billed). version and build are mutually exclusive. The run gate matches the detail gate: invisible apps return 404; visible apps that are not accepting runs return 403 (author self-tests are unrestricted); new runs pinned to a yanked version are rejected (422).

Request

Path parameters

string
必須
App reference: app_<hex> or <namespace>/<app_name>.

Query parameters

number
Maximum seconds to wait for a terminal state. Omit to use the app mode default; 0 returns immediately after start.Range 0 to 60.
integer
Maximum records to produce. The run ends normally when the cap is reached. Use it to control cost and duration.Range ≥ 1.
string
デフォルト:"api"
Channel marker. Default api; SDKs and MCP set their own values. Usable as a filter on run list and billing.
string
Pin to a specific version. Defaults to the latest version.
string
Author debug only. Pin to a build snapshot. Mutually exclusive with version.

Request body

JSON object shaped by the app input_schema. The safest start is to copy an entry from examples in app detail and edit it.

Example request

Response

200 success

The payload is wrapped in data. Fields:
string
必須
Run id. Use it for status, records, and cancel.
string
Publisher username.
string
App name.
string
Pinned version. null for debug runs.
string
Build snapshot pinned by a debug run. null for production runs.
string
production for normal runs; test for author debug runs.
enum
必須
Run state. Values: PENDING / QUEUED / RUNNING / SUCCEEDED / PARTIALLY_SUCCEEDED / FAILED / CANCELLED / EXPIRED.
object
Input echo. Fields marked sensitive in the input contract are redacted.
object
Progress. done / total are reported by the app; status_text is a human-readable status string from the app.
string
Result dataset id.
boolean
true when the run partially succeeded or was cancelled. Produced records remain usable.
boolean
true while cancellation has been requested and the run is still winding down (cooperative stop / partial-result recovery). Always false in terminal states (normalized server-side), so clients need not derive it from state.
string
Start channel.
string
Upstream task id, when present.
string
Start time. Also the anchor for time-range filters and billing attribution.
string
Most recent execution start time. Re-stamped on retry.
string
When a worker first claimed the run. Unlike started_at, this is never rewritten on retry, so it is the anchor for queue time: queued = first_started_at - created_at, and total wall time = finished_at - first_started_at. Deriving queue time from started_at counts earlier attempts as queueing. null only for runs never claimed.
string
End time.
object
Objective usage metering: how much the run did. Kept separate from billing; this is what evaluations compare against.
object
Billing ledger = usage × pricing × billing rules. events[] lists each billable event with quantity, unit price, and amount; total is the sum; charged is whether the charge was applied. Complete only after a terminal state.
object
Error object on failure (code / category / message / retryable).
object[]
First batch of records when the response is already terminal; otherwise null.
object[]
Structured warnings, for example billing-qty-missing.

Errors

Error responses use {"error": {code, category, message, retryable}}. See Errors.

Client libraries

Notes

  • State vocabulary: PENDING, QUEUED, RUNNING, SUCCEEDED, PARTIALLY_SUCCEEDED, FAILED, CANCELLED, EXPIRED. The last five are terminal.
  • Do not start a second run for the same goal just because a wait timed out. Poll the existing run_id first.
  • Failed runs are not billed. Partial success and cancel bill only for produced records.