Advanced APIs

Jobs & async

Research, crawl, domain, large map, and monitor runs are asynchronous. They return a job you poll until it finishes.

Overview

Async operations return a job_id right away. Poll the job until its status is terminal, then read result.

Polling a job

Poll

# 1) Start an async operation, capture job_id
curl https://api.ohsee.tech/research \
  -H "Authorization: Bearer ohsee-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{ "query": "..." }'

# 2) Poll until status is terminal
curl https://api.ohsee.tech/jobs/<job_id> \
  -H "Authorization: Bearer ohsee-<your-key>"

Statuses

queued: accepted, waiting to start.
running: in progress.
succeeded: finished with a full result.
partial: finished with some results.
failed: see error_stage and error_message.

Get a job

GET/jobs/{job_id}

200 OK

{
  "job_id": "9b8c7d6e-...",
  "request_id": "d4e5f6a7",
  "kind": "research",
  "status": "succeeded",
  "credits": { "reserved": 15, "charged": 15, "refunded": 0 },
  "result": { "...": "..." },
  "error_stage": null,
  "error_message": null,
  "created_at": "2026-01-01T12:00:00Z",
  "started_at": "2026-01-01T12:00:01Z",
  "finished_at": "2026-01-01T12:00:18Z"
}

Field	Type	Description
`status`	string	Current job status.
`credits`	object	`reserved`, `charged`, and `refunded` credits.
`result`	object \| null	Operation result once the job succeeds.
`error_stage / error_message`	string \| null	Failure details when a job fails.
`created_at / started_at / finished_at`	string \| null	ISO 8601 timestamps.

List jobs

GET/jobs

Field	Type	Default	Description
`kind`	string	null	Filter by kind: `research`, `map`, `crawl`, `domain`, `monitor_run`.
`limit`	int	50	Maximum jobs to return (up to 100).

Monitors

Credit estimate