CompanyTask

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/desearch-ai/json-schema/desearch-ai-company-task-schema.json",
  "title": "CompanyTask",
  "description": "A Company Search or Company Enrich task. Poll it until `status` is completed, partial, failed or cancelled.",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/desearch-ai-openapi.json#/components/schemas/CompanyTask",
  "properties": {
    "task_id": {
      "type": "string",
      "format": "uuid",
      "title": "Task Id",
      "description": "Id of this task, returned as soon as it is created. Pass it to `GET /desearch/companies/tasks/{task_id}`, the results and export routes, and pause, resume, or cancel."
    },
    "search_type": {
      "type": "string",
      "enum": [
        "company_search",
        "company_enrich"
      ],
      "title": "Search Type"
    },
    "platform": {
      "type": "string",
      "enum": [
        "company",
        "company_enrich"
      ],
      "title": "Platform",
      "description": "The task's service: `company` (Company Search) or `company_enrich` (Company Enrich)."
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "running",
        "pausing",
        "paused",
        "cancelling",
        "completed",
        "partial",
        "failed",
        "cancelled",
        "expired"
      ],
      "title": "Status"
    },
    "stage": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "planning",
            "searching",
            "processing",
            "enriching",
            "finalizing"
          ]
        },
        {
          "type": "null"
        }
      ],
      "title": "Stage",
      "description": "What the task is doing now. `enriching`: every company is published and only the later stages of some of them (leaders, inferred emails, email checks) are left."
    },
    "query": {
      "type": "string",
      "title": "Query",
      "description": "Company Search: the description. Company Enrich: a short label of the domains, e.g. `acme.com, beta.io and 3 more`."
    },
    "count": {
      "type": "integer",
      "title": "Count",
      "description": "Companies asked for (Company Enrich: the domains left after deduplication)."
    },
    "result_count": {
      "type": "integer",
      "title": "Result Count",
      "description": "Companies delivered so far."
    },
    "request": {
      "anyOf": [
        {
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Request",
      "description": "The normalized request. Company Search: `query`, `count`, `min_score`, `exclude`, `roles`, `infer_emails`, `verify_emails`, `filters`. Company Enrich: `domains`, `roles`, `infer_emails`, `verify_emails`."
    },
    "metadata": {
      "additionalProperties": {
        "type": "string"
      },
      "type": "object",
      "title": "Metadata",
      "description": "The `metadata` sent when the task was created (`{}` when none)."
    },
    "interpreted": {
      "anyOf": [
        {
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Interpreted",
      "description": "Company Search: how the description was understood (criteria and the queries it ran)."
    },
    "progress": {
      "type": "object",
      "title": "Progress",
      "description": "Counters while the task runs: `candidates_found`, `candidates_processed`, `qualified`, `filtered` (companies left out, by reason: `unreachable`, `not_a_company`, `below_min_score`, `no_<requirement>`), `enrichment` (`published`, `complete`, `pending`, `failed`), `email_checks` (`checked`, `valid`, `invalid`, `risky`, `unknown`) and `stop_reason`, the worker's internal reason for stopping. Prefer `completion_reason` and `coverage_limited`."
    },
    "errors": {
      "items": {},
      "type": "array",
      "title": "Errors"
    },
    "completion_reason": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "count_reached",
            "all_domains_processed",
            "rounds_exhausted",
            "no_candidates",
            "zero_qualified",
            "candidate_budget",
            "cost_limit",
            "time_limit",
            "cancelled",
            "failed"
          ]
        },
        {
          "type": "null"
        }
      ],
      "title": "Completion Reason",
      "description": "Why the task ended; `null` while it is queued, running or paused. `count_reached`: it delivered `count` companies. `all_domains_processed` (Company Enrich): it read every domain. `rounds_exhausted`: it ran every search it planned and delivered fewer than `count`. `no_candidates`: its searches found no company to check. `zero_qualified`: it checked the companies its searches found and none fit. `candidate_budget`: it checked as many candidates as a task of this `count` may. `cost_limit`: what searching cost reached what its results would bill, so it stopped. `time_limit`: it ran for its maximum time. `cancelled`: it was cancelled. `failed`: an error ended it. Added alongside `status`, which keeps its values: a task that stopped on a budget with fewer than `count` companies is still `completed` — see `coverage_limited`."
    },
    "coverage_limited": {
      "type": "boolean",
      "title": "Coverage Limited",
      "description": "True when the task stopped on a budget (`completion_reason` `cost_limit`, `candidate_budget` or `time_limit`) before reaching `count`: there may be more matching companies than it returned.",
      "default": false
    },
    "warnings": {
      "items": {
        "$ref": "#/$defs/CompanyTaskWarning"
      },
      "type": "array",
      "title": "Warnings",
      "description": "What made part of the task less reliable without failing it. `[]` when nothing did."
    },
    "reserved_cost_usd": {
      "type": "number",
      "title": "Reserved Cost Usd",
      "description": "Amount reserved when the task was created."
    },
    "final_cost_usd": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "title": "Final Cost Usd",
      "description": "Final cost once the task has ended. The rest of the reservation is returned."
    },
    "refunded_usd": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "title": "Refunded Usd"
    },
    "created_by": {
      "anyOf": [
        {
          "$ref": "#/$defs/CompanyTaskCreatedBy"
        },
        {
          "type": "null"
        }
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "title": "Created At"
    },
    "started_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "Started At"
    },
    "paused_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "Paused At"
    },
    "finished_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "Finished At"
    },
    "results_expire_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "Results Expire At"
    },
    "links": {
      "anyOf": [
        {
          "$ref": "#/$defs/CompanyTaskLinks"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "additionalProperties": true,
  "type": "object",
  "required": [
    "task_id",
    "search_type",
    "platform",
    "status",
    "query",
    "count",
    "result_count",
    "reserved_cost_usd",
    "created_at"
  ],
  "$defs": {
    "CompanyTaskCreatedBy": {
      "properties": {
        "user_id": {
          "anyOf": [
            {
              "type": "string",
              "format": "uuid"
            },
            {
              "type": "null"
            }
          ],
          "title": "User Id"
        },
        "api_key_id": {
          "anyOf": [
            {
              "type": "string",
              "format": "uuid"
            },
            {
              "type": "null"
            }
          ],
          "title": "Api Key Id"
        },
        "via": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Via"
        }
      },
      "type": "object",
      "title": "CompanyTaskCreatedBy"
    },
    "CompanyTaskLinks": {
      "properties": {
        "self": {
          "type": "string",
          "title": "Self"
        },
        "results": {
          "type": "string",
          "title": "Results"
        },
        "export": {
          "type": "string",
          "title": "Export"
        }
      },
      "type": "object",
      "required": [
        "self",
        "results",
        "export"
      ],
      "title": "CompanyTaskLinks"
    },
    "CompanyTaskWarning": {
      "properties": {
        "code": {
          "type": "string",
          "title": "Code",
          "description": "What happened: `planning_fallback`, `ai_scoring_unavailable`, `enrichment_time_limit` or `linkedin_verification_unavailable`."
        },
        "message": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Message"
        }
      },
      "additionalProperties": true,
      "type": "object",
      "required": [
        "code"
      ],
      "title": "CompanyTaskWarning",
      "description": "Something that made part of a task less reliable without failing it."
    }
  }
}