> ## 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. # JavaScript client library > Install, initialize, map methods to endpoints, and handle errors with the official JavaScript SDK octoparse-client. `octoparse-client` is the official JavaScript/TypeScript client for Data Hub. It wraps only the public `/v1` REST API. Methods map one-to-one to endpoints, parameter names match REST, and return values are the raw `data` payload. Requires Node.js 18+ or a modern browser runtime with `fetch`. ## Install ```bash theme={null} npm install octoparse-client ``` ## Initialize ```js theme={null} import { Client } from "octoparse-client"; const client = new Client({ apiKey: "" }); ``` | Option | Description | | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `apiKey` | Data Hub API key. If omitted, reads `OCTOPARSE_API_KEY`. If still missing, the client is anonymous and can call only anonymous endpoints. | | `baseUrl` | Service URL. If omitted, reads `OCTOPARSE_BASE_URL`, defaulting to `https://api-datahub.octoparse.com`. Pass this explicitly for local or staging environments. | | `timeout` | Per-request HTTP timeout in milliseconds. Default 90000. | ## Method to endpoint map | Method | Endpoint | Notes | | ------------------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------- | | `meta()` | `GET /v1/meta` | Platform constants | | `search(q, { limit, offset, ... })` | `GET /v1/data-apps` | One page of cards, including `pagination` | | `getApp(appId)` | `GET /v1/data-apps/{app_id}` | Full app detail | | `run(appId, inputs, { wait, maxRecords, version, build })` | `POST /v1/data-apps/{app_id}/runs` | Start a run | | `call(appId, inputs, { maxRecords, timeout, raiseOnFailure, ... })` | `POST` + poll | Blocking helper: wait until terminal or timeout | | `getRun(runId, { wait })` | `GET /v1/runs/{run_id}` | Status and billing snapshot | | `listRunsPage(filters)` | `GET /v1/runs` | One page of runs, including `pagination` | | `listRuns(filters)` | `GET /v1/runs` | One page of runs, items only | | `iterateRuns(filters)` | `GET /v1/runs` | Async iterator that pages automatically | | `cancel(runId)` | `POST /v1/runs/{run_id}/cancel` | Cancel a run | | `getRecords(runId, { offset, limit, fields })` | `GET /v1/runs/{run_id}/records` | One page of result records | | `iterateRecords(runId, { batch, fields })` | `GET /v1/runs/{run_id}/records` | Async iterator that pages automatically | | `exportRecords(runId, format)` | `GET /v1/runs/{run_id}/records` | Full export as `jsonl` / `csv` text | | `listDatasets({ offset, limit })` | `GET /v1/datasets` | Dataset list | | `setDatasetRetention(datasetId, retained)` | `PUT /v1/datasets/{dataset_id}/retention` | Set retention flag | | `getDatasetRecords(datasetId, { offset, limit, fields })` | `GET /v1/datasets/{dataset_id}/records` | One page of dataset records | | `iterateDatasetRecords(datasetId, { batch, fields })` | `GET /v1/datasets/{dataset_id}/records` | Async iterator that pages automatically | | `account()` | `GET /v1/account` | Account info and lifetime spend | | `billing({ groupBy, createdFrom, createdTo, tzOffset })` | `GET /v1/billing` | Billing aggregation | Run-list `filters` support `status`, `dataApp`, `triggeredBy`, `runKind`, `credential`, `createdFrom`, `createdTo`, plus `offset` / `limit`. Publishing, operations, and secrets endpoints are not wrapped; call REST directly. ## Typical usage ```js theme={null} import { Client, ApiError, RunFailed } from "octoparse-client"; const client = new Client({ apiKey: "" }); // Discover const { items } = await client.search("reviews", { limit: 5 }); for (const card of items) console.log(card.app_id, card.namespace, card.app_name); const detail = await client.getApp("carol/reviews-query"); // Run and consume. Timeouts are milliseconds. TimeoutError does not cancel the server-side run. const run = await client.call("carol/reviews-query", { product: "p-9001" }, { maxRecords: 100, timeout: 120_000, raiseOnFailure: true, }); for await (const record of client.iterateRecords(run.run_id)) { console.log(record); } // Non-blocking: start, then poll yourself const started = await client.run("carol/reviews-query", { product: "p-9002" }, { wait: 0 }); const polled = await client.getRun(started.run_id, { wait: 60 }); // Reconcile spend console.log(await client.billing({ groupBy: "data_app", tzOffset: 480 })); for await (const r of client.iterateRuns({ createdFrom: "2026-09-01T00:00:00+08:00" })) { console.log(r.run_id, r.status, r.billing.total); } // Results are kept 90 days by default; mark datasets you need longer await client.setDatasetRetention(run.dataset_id, true); ``` ## Error handling API error responses throw `ApiError` (extends `Error`). Fields match the REST `error` object: | Property | Meaning | | ------------ | --------------------------------------------------------------------- | | `statusCode` | HTTP status | | `code` | Stable error id for branching | | `category` | Broad class | | `message` | English description | | `retryable` | Whether the same request can be retried | | `details` | Field-level issues on input validation failure, otherwise `undefined` | ```js theme={null} import { ApiError } from "octoparse-client"; try { await client.run("carol/reviews-query", {}); } catch (e) { if (e instanceof ApiError && e.code === "invalid-input") { for (const d of e.details ?? []) console.log(d.path, d.message); } else if (e instanceof ApiError && e.retryable) { // back off and retry } else { throw e; } } ``` `RunFailed` is thrown when `call()` uses `raiseOnFailure: true` and the run ends in `FAILED` / `CANCELLED` / `EXPIRED`. Its `run` property holds the full run object. ## App references `getApp()`, `run()`, `call()`, and the run-list `dataApp` filter accept both forms: two-segment `/` (human-readable, breaks after rename) and stable `app_id` (`app_`, survives rename). For long-lived integrations, store `app_id`. Point-to-point shared apps are absent from market search; use `search("", { sharedWith: "me" })`.