Worker Response Examples

This guide provides concrete examples of responses returned by the polling system for three types of workers. To obtain exact specifications for a specific worker, use the GET /v1/workers/{worker_id} endpoint.

Result Structural Overview

Once a job reaches the SUCCEEDED state, the response systematically follows this schema:

Field	Role
job_id	Unique identifier of the job.
status	Terminal state (SUCCEEDED).
output	Result container (kind, data, items, meta).
files	List of generated binary assets (temporary URLs).
cost	Detailed breakdown of the applied billing.

Reading the output Field

The output.kind field determines how to extract data:

• object : The primary result is located in output.data.
• list : Results are enumerated in output.items.
• meta : Contains transverse information (success status, warnings, pagination metadata).

Event-Based Billing Workers

For per_event workers, ensure you configure the max_billable_events parameter during submission to control your costs.

---

Case Study 1: image-format-converter

This worker transforms images between different formats. It is billed per execution (per_run).

Flow: Image URL Input $\rightarrow$ Processing $\rightarrow$ Binary File Generation.

{
  "job_id": "job_01JA…",
  "worker_id": "image-format-converter",
  "status": "SUCCEEDED",
  "output": {
    "kind": "object",
    "data": {
      "source_format": "png",
      "target_format": "jpeg",
      "width": 100,
      "height": 100,
      "mime_type": "image/jpeg",
      "output_filename": "converted.jpg"
    },
    "items": [],
    "meta": { "ok": true, "warnings": [] }
  },
  "files": [
    {
      "id": "file_abc",
      "name": "converted.jpg",
      "content_type": "image/jpeg",
      "size_bytes": 1234,
      "url": "https://storage.seek-api.com/..."
    }
  ],
  "cost": { "total_usd": 0.0005, "run_usd": 0.0005, "infra_usd": 0.0, "billing_mode": "per_run" }
}

---

Case Study 2: email-verifier

Email address validation worker. Event-based billing.

Flow: List of Emails $\rightarrow$ SMTP/Syntax Checks $\rightarrow$ List of Results.

{
  "output": {
    "kind": "list",
    "data": null,
    "items": [
      {
        "email": "user@example.com",
        "status": "valid",
        "score": 95,
        "syntax_valid": true,
        "mx_found": true
      }
    ],
    "meta": { "processed_count": 1, "error_count": 0 }
  }
}

---

Case Study 3: leboncoin-real-estate

Real estate data extraction worker. Event-based billing.

Flow: Search Criteria $\rightarrow$ Scraping $\rightarrow$ Structured Listing.

{
  "output": {
    "kind": "list",
    "data": null,
    "items": [
      {
        "id": 2836759210,
        "title": "Apartment T3 Lyon Centre",
        "price_eur": 320000,
        "location_city": "Lyon"
      }
    ],
    "meta": {
      "scraped_at": "2026-01-15T10:00:00Z",
      "total_available": 247,
      "ads_delivered": 1
    }
  }
}

---

Quick Test Tool

To validate your integrations in a local environment, you can use our test script:

export SEEK_API_KEY='YOUR_API_KEY'
python docs/scripts/smoke_workers.py

Note: You can override the base URL via the SEEK_API_BASE variable (default: https://api.seek-api.com).