List runs

List runs

curl --request GET \
  --url https://api.example.com/v1/runs

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/runs",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/runs"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/runs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "items": [
    {
      "run_id": "<string>",
      "namespace": "<string>",
      "app_name": "<string>",
      "app_version": "<string>",
      "build_id": "<string>",
      "run_kind": "<string>",
      "state": {},
      "input": {},
      "progress": {
        "done": 123,
        "total": 123,
        "status_text": "<string>"
      },
      "dataset_id": "<string>",
      "partial": true,
      "cancel_requested": true,
      "triggered_by": "<string>",
      "upstream_ref": "<string>",
      "created_at": "<string>",
      "started_at": "<string>",
      "first_started_at": "<string>",
      "finished_at": "<string>",
      "usage": {
        "metrics": {},
        "duration_ms": 123
      },
      "billing": {
        "events": [
          {}
        ],
        "total": 123,
        "currency": "<string>",
        "charged": true
      },
      "error": {
        "code": "<string>",
        "category": "<string>",
        "message": "<string>",
        "retryable": true,
        "retry_after": 123,
        "item_index": 123,
        "details": [
          {}
        ]
      }
    }
  ],
  "pagination": {
    "offset": 123,
    "limit": 123,
    "count": 123,
    "total": 123,
    "has_more": true
  }
}

GET

runs

List runs

curl --request GET \
  --url https://api.example.com/v1/runs

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/runs",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/runs"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/runs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "items": [
    {
      "run_id": "<string>",
      "namespace": "<string>",
      "app_name": "<string>",
      "app_version": "<string>",
      "build_id": "<string>",
      "run_kind": "<string>",
      "state": {},
      "input": {},
      "progress": {
        "done": 123,
        "total": 123,
        "status_text": "<string>"
      },
      "dataset_id": "<string>",
      "partial": true,
      "cancel_requested": true,
      "triggered_by": "<string>",
      "upstream_ref": "<string>",
      "created_at": "<string>",
      "started_at": "<string>",
      "first_started_at": "<string>",
      "finished_at": "<string>",
      "usage": {
        "metrics": {},
        "duration_ms": 123
      },
      "billing": {
        "events": [
          {}
        ],
        "total": 123,
        "currency": "<string>",
        "charged": true
      },
      "error": {
        "code": "<string>",
        "category": "<string>",
        "message": "<string>",
        "retryable": true,
        "retry_after": 123,
        "item_index": 123,
        "details": [
          {}
        ]
      }
    }
  ],
  "pagination": {
    "offset": 123,
    "limit": 123,
    "count": 123,
    "total": 123,
    "has_more": true
  }
}

GET https://api-datahub.octoparse.com/v1/runs Authentication: API key required (Authorization: Bearer <API Key>). All runs you started. Ownership is by account: runs started with an API key, SDK, MCP, or web login appear in the same list. Always newest-first by start time. pagination.total is the filtered total. Filters can be combined. status accepts comma-separated values (OR). credential is the non-sensitive stable id of the starting credential, useful for tracking which key is consuming quota. created_from / created_to use start time, start inclusive and end exclusive. The vocabulary matches Billing aggregation: pass a billing group key through unchanged to drill into the matching runs. Each item includes billing and usage, so per-run reconciliation does not need a separate detail call. Input echo redaction matches run detail.

Request

Query parameters

string

Run state. Comma-separated multi-value. Values outside the vocabulary return 400.

string

Stable id of the starting credential. Take the value from billing aggregation group_by=credential → credential.

string

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

string

Start channel, for example api / sdk / mcp / cli / web.

string

Start-time lower bound, inclusive. Absolute ISO-8601 timestamp.

string

Start-time upper bound, exclusive.

string

production for normal runs; test for author debug runs.Values: test / production.

integer

default:"0"

Pagination offset.Range ≥ 0.

integer

default:"50"

Page size, max 200.Range 1 to 200.

Example request

curl \
  -H "Authorization: Bearer $OCTOPARSE_API_KEY" \
  "https://api-datahub.octoparse.com/v1/runs?data_app=carol/probe-b&status=SUCCEEDED,PARTIALLY_SUCCEEDED&limit=50"

Response

200 success

{
  "data": {
    "items": [
      {
        "run_id": "run_3b750088f51c",
        "namespace": "carol",
        "app_name": "probe-b",
        "app_version": "0.1.0",
        "build_id": null,
        "run_kind": "production",
        "state": "RUNNING",
        "input": {
          "product": "p-doc"
        },
        "progress": {
          "done": 0,
          "total": null,
          "status_text": null
        },
        "dataset_id": "ds_ec3ba97b8534",
        "partial": false,
        "cancel_requested": false,
        "triggered_by": "api",
        "upstream_ref": null,
        "created_at": "2026-09-15T07:45:41.876601+00:00",
        "started_at": "2026-09-15T07:45:41.883082+00:00",
        "first_started_at": "2026-09-15T07:45:41.883082+00:00",
        "finished_at": null,
        "usage": {
          "metrics": {
            "records_collected": 0
          },
          "duration_ms": null
        },
        "billing": {
          "events": [],
          "total": 0.0,
          "currency": "USD",
          "charged": false
        },
        "error": null
      },
      "…"
    ],
    "pagination": {
      "offset": 0,
      "limit": 2,
      "count": 2,
      "total": 2,
      "has_more": false
    }
  }
}

The payload is wrapped in data. Fields:

object[]

required

Run list. Each item matches run detail fields (without sample_records).

Show fields

string

required

—

string

—

string

—

string

—

string

—

string

—

enum

required

Values: PENDING / QUEUED / RUNNING / SUCCEEDED / PARTIALLY_SUCCEEDED / FAILED / CANCELLED / EXPIRED.

object

—

object

—

Show fields

integer

—

integer

—

string

—

string

—

boolean

—

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

—

string

—

string

—

string

—

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

—

object

Objective usage metering: how much the run did. Kept separate from billing; this is what evaluations compare against.

Show fields

object

—

integer

—

object

Billing ledger = usage × pricing × billing rules: how much is charged.

Show fields

object[]

—

number

—

string

—

boolean

—

object

—

Show fields

string

required

—

string

—

string

required

—

boolean

—

number

—

integer

—

object[]

—

object

Pagination object.

Show fields

integer

—

integer

—

integer

—

integer

—

boolean

—

Errors

HTTP	`code`	`category`	Description
401	`unauthorized`	`forbidden`	Missing or invalid API key.
400	`invalid-status`	`invalid_input`	`status` contains a value outside the vocabulary.

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

Client libraries

# Auto-paginate
for r in client.iterate_runs(data_app="carol/probe-b", created_from="2026-09-01T00:00:00+08:00"):
    print(r["run_id"], r["state"], r["billing"]["total"])

# Use the page form when you need totals
page = client.list_runs_page(status="QUEUED,RUNNING", limit=50)
print(page["pagination"]["total"])

// Auto-paginate
for await (const r of client.iterateRuns({ dataApp: "carol/probe-b", createdFrom: "2026-09-01T00:00:00+08:00" })) {
  console.log(r.run_id, r.state, r.billing.total);
}

// Use the page form when you need totals
const page = await client.listRunsPage({ status: "QUEUED,RUNNING", limit: 50 });
console.log(page.pagination.total);

GET STARTED

QUICK START

REFERENCE

DATA HUB API

Request

Query parameters

Example request

Response

200 success

Errors

Client libraries

​Request

​Query parameters

​Example request

​Response

​200 success

​Errors

​Client libraries

Request

Query parameters

Example request

Response

200 success

Errors

Client libraries