Runs & Results
Start a run
Start a Data App run with inputs that satisfy the input contract. Optionally wait for the result.
POST
Start a run
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.modedefault.syncapps wait until a terminal state (capped by the appexecution.timeout_seconds);asyncapps return arun_idimmediately. - Explicit 0–60: both modes behave the same and wait at most
waitseconds.wait=0returns as soon as the run is queued. For asyncapp you can take therun_idfirst, then long-poll with Get a runwait.
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
required
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
default:"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 appinput_schema. The safest start is to copy an entry from examples in app detail and edit it.
Example request
Response
200 success
data. Fields:
string
required
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
required
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_idfirst. - Failed runs are not billed. Partial success and cancel bill only for produced records.