Polling & Result Retrieval

Seek-api job processing is asynchronous. Upon task submission, the API returns a job_uuid used to poll for progress until a terminal state is reached.

Job Lifecycle

The execution flow follows a strictly defined state progression:

ACCEPTED → QUEUED → STARTING → RUNNING → SUCCEEDED
                                        → FAILED
                                        → TIMED_OUT
                                        → CANCELED

State	Description
`ACCEPTED`	Request received and validated by the API
`QUEUED`	Task awaiting resource allocation
`STARTING`	Initializing the execution environment
`RUNNING`	Worker currently processing the task
`SUCCEEDED`	Successful execution — data available in `output`
`FAILED`	Execution failure — details available in `error`
`TIMED_OUT`	Maximum execution time exceeded
`CANCELED`	Task canceled manually or by the system

States SUCCEEDED, FAILED, TIMED_OUT, and CANCELED are terminal: no further state transitions are possible.

Polling Endpoint

Use the job_uuid returned by the POST /v1/workers/{worker_id}/jobs call:

GET https://api.seek-api.com/v1/jobs/{job_uuid}
x-api-key: YOUR_API_KEY

The job_uuid value corresponds to the job_id field in the JSON response.

Optimized Response Structure

To maximize performance and facilitate parsing, the response uses a compact format:

{
  "job_id": "job_01jabcdef123456789",
  "worker_id": "text-summarizer",
  "status": "SUCCEEDED",
  "timestamps": {
    "submitted_at": "2026-01-15T10:30:00.000Z",
    "started_at": "2026-01-15T10:30:02.150Z",
    "finished_at": "2026-01-15T10:30:03.390Z",
    "duration_ms": 1240
  },
  "output": {
    "kind": "object",
    "data": { "message": "generated summary" },
    "items": [],
    "meta": {}
  },
  "files": [],
  "cost": {
    "total_usd": 0.01,
    "run_usd": 0.01,
    "infra_usd": 0.0,
    "billing_mode": "per_run"
  },
  "error": null
}

Field	Description
`output.kind`	Defines the result structure: `object` (data in `data`), `list` (data in `items`), or `empty`.
`output.meta`	Complementary metadata provided by the worker (e.g., warnings, stats).
`files`	List of generated files with presigned download URLs.
`cost`	Financial details of the execution and the applied billing mode.
`error`	Contains `code` and `message` in case of failure; otherwise `null`.

Implementing the Polling Loop

For a robust integration, we recommend implementing a polling mechanism with a timeout.

JavaScript
Python

async function waitForJob(jobUuid, apiKey, { intervalMs = 2000, timeoutMs = 60000 } = {}) {
  const TERMINAL_STATES = new Set(['SUCCEEDED', 'FAILED', 'TIMED_OUT', 'CANCELED']);
  const deadline = Date.now() + timeoutMs;

  while (Date.now() < deadline) {
    const res = await fetch(`https://api.seek-api.com/v1/jobs/${jobUuid}`, {
      headers: { 'x-api-key': apiKey },
    });

    if (!res.ok) throw new Error(`HTTP Error: ${res.status}`);

    const job = await res.json();
    if (TERMINAL_STATES.has(job.status)) return job;

    await new Promise((resolve) => setTimeout(resolve, intervalMs));
  }

  throw new Error(`Timeout: Job ${jobUuid} did not reach terminal state after ${timeoutMs}ms`);
}

const job = await waitForJob('job_01jabcdef123456789', 'YOUR_API_KEY');
if (job.status === 'SUCCEEDED') {
  console.log('Result:', job.output);
} else {
  console.error('Job failed:', job.error);
}

import time
import httpx

TERMINAL_STATES = {"SUCCEEDED", "FAILED", "TIMED_OUT", "CANCELED"}

def wait_for_job(
    job_uuid: str,
    api_key: str,
    *,
    interval_s: float = 2.0,
    timeout_s: float = 60.0,
) -> dict:
    deadline = time.monotonic() + timeout_s

    with httpx.Client() as client:
        while time.monotonic() < deadline:
            response = client.get(
                f"https://api.seek-api.com/v1/jobs/{job_uuid}",
                headers={"x-api-key": api_key},
            )
            response.raise_for_status()
            job = response.json()

            if job["status"] in TERMINAL_STATES:
                return job

            time.sleep(interval_s)
    raise TimeoutError(f"Job {job_uuid} pending after {timeout_s}s")

job = wait_for_job("job_01jabcdef123456789", "YOUR_API_KEY")
if job["status"] == "SUCCEEDED":
    print(job["output"])
else:
    print("Error:", job["error"])

Temporary File Management

Generated binary files (exports, images, etc.) are listed in the files array. Each entry contains a secure, temporary URL.

{
  "files": [
    {
      "id": "export_123",
      "name": "export.csv",
      "content_type": "text/csv",
      "size_bytes": 1024,
      "url": "https://storage.seek-api.com/..."
    }
  ]
}

Frequency Recommendations

The polling interval should be adjusted based on the estimated processing time to optimize responsiveness while limiting network overhead.

Estimated Duration	Recommended Interval
< 5 seconds	1 second
5 – 30 seconds	2 seconds
30s – 5 minutes	5 seconds
> 5 minutes	10 – 30 seconds