> ## Documentation Index > Fetch the complete documentation index at: https://www.octoparse.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Start a run > The request body is an instance of the app's input contract (strictly validated). `wait` decides whether the call holds for the result. Omitted: the app's `execution.mode` default applies — sync apps hold until terminal (up to the app's `execution.timeout_seconds`), async apps return a run_id immediately. Given explicitly (0–60 s): the same for both modes — hold at most `wait` seconds for the terminal state; `wait=0` returns right after enqueue, so a sync app can be started without waiting and polled via GET /runs/{run_id}?wait=. Whenever the run is terminal on return, `sample_records` carries the first records. `version` pins the run to a historical version (contract and price both follow that version); defaults to the latest. `build` is a debug run (owner only): pins an immutable Build snapshot (run_kind=test, excluded from public statistics; billing applies as usual — the owner pays for their own debugging, no special-casing); mutually exclusive with `version`. The run gate matches the detail gate: draft/private owner only, shared per grant list — not visible means 404 (prevents existence leaks). Visible but under maintenance (accepting_runs=false) is 403, with the owner's self-tests exempt. New runs pinned to a yanked version are rejected (422 version-yanked; runs in flight are unaffected). ## OpenAPI ````yaml /jp/datahub/api/openapi.json post /v1/data-apps/{app_id}/runs openapi: 3.1.0 info: title: DataHub API version: 0.2.0 description: Public /v1 contract of Octoparse DataHub. Internal channels are excluded. servers: - url: https://api-datahub.octoparse.com security: - bearerAuth: [] tags: - name: Discovery description: >- Anonymous access: platform metadata (currency), data app search, detail and input contract, machine-readable manifest spec. - name: Publishing description: >- Self-service publishing channel (API Key auth), two-phase: validate first (validate / package, nothing persisted), then publish (POST /data-apps, the submission goes live as a new Release). api kind (declarative integration) becomes visible on publish; code kind (code package) returns 202 and enters an async image build; once ready it is promoted to a Release, visible and runnable. Poll progress via GET /data-apps/{ref}/builds. - name: Runs & Results description: >- Start / query / cancel runs and read result records with pagination. Business inputs go in the request body; platform run options (wait, max_records) go in query parameters. - name: Datasets description: >- Metadata and record access for platform datasets (including seeded stock data). - name: Account description: Account info and cumulative usage for the current API Key. - name: Secrets description: >- CRUD for upstream credentials (environment entries referenced by manifest `runtime.env`). Plaintext is write-only: every read returns a mask. paths: /v1/data-apps/{app_id}/runs: post: tags: - Runs & Results summary: Start a run description: |- The request body is an instance of the app's input contract (strictly validated). `wait` decides whether the call holds for the result. Omitted: the app's `execution.mode` default applies — sync apps hold until terminal (up to the app's `execution.timeout_seconds`), async apps return a run_id immediately. Given explicitly (0–60 s): the same for both modes — hold at most `wait` seconds for the terminal state; `wait=0` returns right after enqueue, so a sync app can be started without waiting and polled via GET /runs/{run_id}?wait=. Whenever the run is terminal on return, `sample_records` carries the first records. `version` pins the run to a historical version (contract and price both follow that version); defaults to the latest. `build` is a debug run (owner only): pins an immutable Build snapshot (run_kind=test, excluded from public statistics; billing applies as usual — the owner pays for their own debugging, no special-casing); mutually exclusive with `version`. The run gate matches the detail gate: draft/private owner only, shared per grant list — not visible means 404 (prevents existence leaks). Visible but under maintenance (accepting_runs=false) is 403, with the owner's self-tests exempt. New runs pinned to a yanked version are rejected (422 version-yanked; runs in flight are unaffected). operationId: run_data_app_v1_data_apps__app_id__runs_post parameters: - name: app_id in: path required: true schema: type: string title: App Id - name: wait in: query required: false schema: anyOf: - type: number maximum: 60 minimum: 0 - type: 'null' title: Wait - name: max_records in: query required: false schema: anyOf: - type: integer minimum: 1 - type: 'null' title: Max Records - name: triggered_by in: query required: false schema: type: string pattern: ^[a-z][a-z0-9_-]{0,31}$ default: api title: Triggered By - name: version in: query required: false schema: anyOf: - type: string - type: 'null' title: Version - name: build in: query required: false schema: anyOf: - type: string - type: 'null' title: Build requestBody: required: true content: application/json: schema: type: object additionalProperties: true title: Body responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/DataEnvelope_RunWithSamples_' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: DataEnvelope_RunWithSamples_: properties: data: $ref: '#/components/schemas/RunWithSamples' type: object required: - data title: DataEnvelope[RunWithSamples] HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError RunWithSamples: properties: run_id: type: string title: Run Id namespace: anyOf: - type: string - type: 'null' title: Namespace app_name: type: string title: App Name default: '' app_version: anyOf: - type: string - type: 'null' title: App Version build_id: anyOf: - type: string - type: 'null' title: Build Id run_kind: type: string title: Run Kind default: production state: $ref: '#/components/schemas/RunState' input: additionalProperties: true type: object title: Input progress: $ref: '#/components/schemas/Progress' dataset_id: anyOf: - type: string - type: 'null' title: Dataset Id partial: type: boolean title: Partial default: false cancel_requested: type: boolean title: Cancel Requested description: >- 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 consumers need not derive it from state default: false triggered_by: type: string title: Triggered By default: api upstream_ref: anyOf: - type: string - type: 'null' title: Upstream Ref created_at: anyOf: - type: string - type: 'null' title: Created At started_at: anyOf: - type: string - type: 'null' title: Started At first_started_at: anyOf: - type: string - type: 'null' title: First Started At description: >- when the run was first claimed by a worker. Unlike started_at, which is re-stamped on every retry, this one is never rewritten, 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 the earlier attempts' execution as queueing. Null only for runs never claimed. finished_at: anyOf: - type: string - type: 'null' title: Finished At usage: $ref: '#/components/schemas/Usage' billing: $ref: '#/components/schemas/Billing' error: anyOf: - $ref: '#/components/schemas/ApiError' - type: 'null' sample_records: anyOf: - items: additionalProperties: true type: object type: array - type: 'null' title: Sample Records warnings: items: $ref: '#/components/schemas/RunWarning' type: array title: Warnings type: object required: - run_id - state title: RunWithSamples ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError RunState: type: string enum: - PENDING - QUEUED - RUNNING - SUCCEEDED - PARTIALLY_SUCCEEDED - FAILED - CANCELLED - EXPIRED title: RunState Progress: properties: done: type: integer title: Done default: 0 total: anyOf: - type: integer - type: 'null' title: Total status_text: anyOf: - type: string - type: 'null' title: Status Text type: object title: Progress Usage: properties: metrics: additionalProperties: type: integer type: object title: Metrics duration_ms: anyOf: - type: integer - type: 'null' title: Duration Ms type: object title: Usage description: |- Objective usage metering: how much the run did (kept separate from Billing; this is what evaluations compare against). Billing: properties: events: items: $ref: '#/components/schemas/BillingEvent' type: array title: Events total: type: number title: Total default: 0 currency: type: string title: Currency charged: type: boolean title: Charged default: true type: object title: Billing description: 'Billing ledger = Usage x pricing x billing_rules: how much is charged.' ApiError: properties: code: type: string title: Code category: type: string title: Category default: internal message: type: string title: Message retryable: type: boolean title: Retryable default: false retry_after: anyOf: - type: number - type: 'null' title: Retry After item_index: anyOf: - type: integer - type: 'null' title: Item Index details: anyOf: - items: additionalProperties: type: string type: object type: array - type: 'null' title: Details type: object required: - code - message title: ApiError RunWarning: properties: code: type: string title: Code event: type: string title: Event default: '' detail: additionalProperties: true type: object title: Detail count: type: integer title: Count default: 0 updated_at: anyOf: - type: string - type: 'null' title: Updated At type: object required: - code title: RunWarning description: |- Structured run-level warning (e.g. billing-qty-missing: the quantity field is missing, non-numeric, or negative, so it is charged as 0). Surfaced only in the single-run detail, never in lists. BillingEvent: properties: event: type: string title: Event label: type: string title: Label default: '' qty: type: number title: Qty unit_price: type: number title: Unit Price amount: type: number title: Amount unit_size: anyOf: - type: integer - type: 'null' title: Unit Size raw_qty: anyOf: - type: number - type: 'null' title: Raw Qty type: object required: - event - qty - unit_price - amount title: BillingEvent securitySchemes: bearerAuth: type: http scheme: bearer description: DataHub API Key ````