Call a Worker

This guide details the lifecycle of a request to a Seek-api worker, from exploring the catalogue to retrieving structured results.

Prerequisites

A valid API key is required to authenticate your requests. If you don’t have one, please visit the Generate API Key section.

Step 1 — Explore the Worker Catalogue

The API allows you to dynamically list available capabilities to adapt your integrations.

GET https://api.seek-api.com/v1/workers

This endpoint is public. The response contains a workers array detailing the specifications of each worker (identifier, pricing, category, tags):

{
  "workers": [
    {
      "worker_id": "text-summarizer",
      "name": "Text Summarizer",
      "price_per_run_usd": 0.01,
      "billing_mode": "per_run",
      "short_description": "Generates concise summaries in bullet points.",
      "category": "ai-agents",
      "tags": ["text", "summary"]
    }
  ]
}

You can refine your search using category filters or text queries:

GET https://api.seek-api.com/v1/workers?category=ai-agents&q=summarizer

Step 2 — Analyze the Input Schema

Each worker has a strict interface contract. Before submission, retrieve the input schema (input_schema) to ensure your payload is valid:

GET https://api.seek-api.com/v1/workers/text-summarizer

The response provides technical details, including the JSON schema, README content, and maximum timeout:

{
  "worker_id": "text-summarizer",
  "name": "Text Summarizer",
  "status": "ACTIVE",
  "billing_mode": "per_run",
  "timeout_seconds": 60,
  "input_schema": {
    "type": "object",
    "properties": {
      "text": { "type": "string", "description": "Source text to summarize" },
      "max_points": { "type": "integer", "default": 5 }
    },
    "required": ["text"]
  },
  "output_schema": {},
  "readme_content": null
}

Step 3 — Submit a Task (Job)

Once the schema is validated, submit your request. Processing is asynchronous to ensure high availability.

curl -X POST https://api.seek-api.com/v1/workers/text-summarizer/jobs \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Seek-api enables executing scalable tasks via an HTTP API...",
    "max_points": 3
  }'

const response = await fetch(
  'https://api.seek-api.com/v1/workers/text-summarizer/jobs',
  {
    method: 'POST',
    headers: {
      'x-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      text: 'Seek-api enables executing scalable tasks via an HTTP API...',
      max_points: 3,
    }),
  }
);

const job = await response.json();
console.log(job.job_uuid); // "abc-123-def-456"

import httpx

response = httpx.post(
    "https://api.seek-api.com/v1/workers/text-summarizer/jobs",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "text": "Seek-api enables executing scalable tasks via an HTTP API...",
        "max_points": 3,
    },
)

job = response.json()
print(job["job_uuid"])  # "abc-123-def-456"

`202 Accepted` Response

The API confirms the task has been accepted:

{
  "job_uuid": "job_01jabcdef123456789",
  "worker_id": "text-summarizer",
  "status": "QUEUED",
  "submitted_at": "2026-01-15T10:30:00.000Z"
}

The job is placed in a priority queue. You receive a job_uuid to track progress.

For workers configured with billing_mode: per_event, you can set a consumption ceiling via the max_billable_events parameter in the request body. Refer to the worker’s README for more details.

{ "prompt": "...", "max_billable_events": 100 }

Step 4 — Retrieve Results

Poll the job status using the job_uuid provided during submission:

GET https://api.seek-api.com/v1/jobs/job_01jabcdef123456789
x-api-key: YOUR_API_KEY

Once the status changes to SUCCEEDED, the data is available in the output object, timing metrics in timestamps, and the final cost in cost.

{
  "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.000Z",
    "finished_at": "2026-01-15T10:30:03.200Z",
    "duration_ms": 1200
  },
  "output": {
    "kind": "object",
    "data": {
      "points": [
        "Seek-api exposes scalable workers via an HTTP API.",
        "Authentication is secured via API key.",
        "Result retrieval is handled via polling."
      ]
    },
    "items": [],
    "meta": {}
  },
  "files": [],
  "cost": {
    "total_usd": 0.01,
    "run_usd": 0.01,
    "infra_usd": 0.0,
    "billing_mode": "per_run"
  },
  "error": null
}

For a robust retrieval strategy, see our Polling & Results guide and explore Response Examples.