Get a job

GET /v1/jobs/:id reads the current state of a job. There are two kinds of id, and they return two different shapes.

string

required

A job id. Parent ids have no dots (job_8t2q). Child ids are dotted, with three segments (job_8t2q.chatgpt.us).

Parent vs. child ids

When you submit a search, you get back a parent job and one child per surface × region.

A parent id (job_8t2q) returns a rollup: the parent’s status plus a list of its children. Use it to track fan-out progress.
A child id (job_8t2q.chatgpt.us) returns the canonical Envelope, the answer and its provenance for exactly one surface in one region.

Child ids follow the form job_<id>.<surface>.<regionKey> — the region key is the lowercased country[:city][:language] (or GLOBAL when untargeted). You get them from the children array on the submit response (202) or from a parent read.

Parent response

curl https://api.aisearchapi.dev/v1/jobs/job_8t2q \
  -H "Authorization: Bearer $AISEARCH_API_KEY"

const res = await fetch('https://api.aisearchapi.dev/v1/jobs/job_8t2q', {
  headers: { Authorization: `Bearer ${process.env.AISEARCH_API_KEY}` },
});
const job = await res.json();

import os, requests

res = requests.get(
    "https://api.aisearchapi.dev/v1/jobs/job_8t2q",
    headers={"Authorization": f"Bearer {os.environ['AISEARCH_API_KEY']}"},
)
job = res.json()

Parent

{
  "job": {
    "id": "job_8t2q",
    "status": "processing",
    "children": [
      "job_8t2q.chatgpt.us",
      "job_8t2q.claude.us",
      "job_8t2q.perplexity.us"
    ]
  },
  "children": [
    {
      "id": "job_8t2q.chatgpt.us",
      "surface": "chatgpt",
      "region": "us",
      "status": "completed"
    },
    {
      "id": "job_8t2q.claude.us",
      "surface": "claude",
      "region": "us",
      "status": "processing"
    },
    {
      "id": "job_8t2q.perplexity.us",
      "surface": "perplexity",
      "region": "us",
      "status": "queued"
    }
  ]
}

job

object

Show properties

string

The parent job id.

status

string

The rolled-up job status. See status values.

children

object[]

One entry per surface × region.

Show properties

string

The child id — fetch it to read the Envelope.

surface

string

The surface for this child.

region

string

The canonical region key (e.g. us, gb:en, GLOBAL).

status

string

This child’s status.

Child response (the Envelope)

Fetch a child id to get the full result for one surface.

curl https://api.aisearchapi.dev/v1/jobs/job_8t2q.chatgpt.us \
  -H "Authorization: Bearer $AISEARCH_API_KEY"

const res = await fetch(
  'https://api.aisearchapi.dev/v1/jobs/job_8t2q.chatgpt.us',
  { headers: { Authorization: `Bearer ${process.env.AISEARCH_API_KEY}` } },
);
const envelope = await res.json();

import os, requests

res = requests.get(
    "https://api.aisearchapi.dev/v1/jobs/job_8t2q.chatgpt.us",
    headers={"Authorization": f"Bearer {os.environ['AISEARCH_API_KEY']}"},
)
envelope = res.json()

Envelope

{
  "job": {
    "id": "job_8t2q.chatgpt.us",
    "query": "best CRM for startups",
    "surface": "chatgpt",
    "region": "us",
    "status": "completed",
    "warnings": [],
    "requestedAt": "2026-06-27T00:00:00.000Z",
    "completedAt": "2026-06-27T00:00:03.120Z"
  },
  "provenance": {
    "model": {
      "providerId": null,
      "observedLabel": "gpt-5-3",
      "inferred": true,
      "confidence": 0.6
    },
    "webSearch": { "enabled": true, "known": true },
    "triggerState": "search",
    "persona": "anonymous_default_model",
    "loginState": "logged_out",
    "surfacePresent": true,
    "region": { "requested": "US", "effective": "US" },
    "capturedAt": "2026-06-27T00:00:03.000Z",
    "callUuid": "call_e9e13810ec46f8bbb814497766d1d05c",
    "schemaVersion": "2026-06-27"
  },
  "answer": {
    "text": "For startups, the top CRMs are HubSpot, Attio and Pipedrive...",
    "markdown": "For startups, the top CRMs are **HubSpot**, **Attio** and **Pipedrive**...",
    "blocks": [
      { "type": "paragraph", "text": "For startups...", "referenceIds": [0, 1] }
    ]
  },
  "evidence": {
    "sources": [
      {
        "id": 0,
        "url": "https://www.hubspot.com",
        "title": "HubSpot",
        "role": "cited",
        "cited": true,
        "charRanges": [[27, 34]]
      },
      {
        "id": 1,
        "url": "https://attio.com",
        "title": "Attio",
        "role": "cited",
        "cited": true,
        "charRanges": [[36, 41]]
      }
    ],
    "fanOut": {
      "provenance": "observed",
      "queries": ["best crm for startups 2026"]
    },
    "mentions": null,
    "shopping": null,
    "ads": null
  },
  "credits": { "creditsToCharge": 5, "creditsCharged": 5 }
}

The Envelope has four sections: job, provenance, answer, and evidence (plus optional html and credits). See The Envelope for a full field-by-field reference.

If a surface returns nothing, the child still finishes as completed with provenance.surfacePresent: false, a surface_absent warning, and an empty answer. An empty capture costs no credits.

Status values

A job is always in exactly one status.

Active statuses

queued | running | processing

The job is still running. Keep polling, or wait for a webhook. A child that is claimed but not yet persisted returns { "job": { "id": ..., "status": "running" }, "children": [] }.

Terminal statuses

completed | partial | failed | canceled | expired

The job is done. Stop polling on any of these.

For a parent, the rollup is derived from its children: completed when all children completed, failed when all failed, and partial on a mix.

A poll loop must stop on any terminal state — not just completed. Treating partial, failed, canceled, or expired as “keep waiting” will loop forever.

Polling loop

Poll the parent until it reaches a terminal state, then read each child.

Poll a parent until terminal

JOB_ID="job_8t2q"

while true; do
  BODY=$(curl -s "https://api.aisearchapi.dev/v1/jobs/$JOB_ID" \
    -H "Authorization: Bearer $AISEARCH_API_KEY")
  STATUS=$(echo "$BODY" | jq -r '.job.status')
  echo "status: $STATUS"

  case "$STATUS" in
    completed|partial|failed|canceled|expired)
      echo "$BODY" | jq -r '.children[].id' | while read -r CHILD; do
        curl -s "https://api.aisearchapi.dev/v1/jobs/$CHILD" \
          -H "Authorization: Bearer $AISEARCH_API_KEY" | jq '.answer.text'
      done
      break
      ;;
  esac
  sleep 2
done

For fan-out across many surfaces or regions, prefer webhooks over polling. You get a signed POST the moment each child reaches a terminal state — no loop, no wasted requests, and each child’s Envelope is delivered inline.

Errors

404

JOB_NOT_FOUND

No job exists for the given id, or it has expired. Check the id — remember that parent ids have no dots and child ids do.

404

{
  "code": "JOB_NOT_FOUND",
  "error": "no job with id 'job_8t2q.chatgpt.us'",
  "request_id": "req_9f2c1a7e4b5d48f1a3c6e8d0b2a4f6c8",
  "docs_url": "https://docs.aisearchapi.dev/guides/errors#job_not_found"
}

See the full error reference for every code and the shared error shape.

Submit a search

Start a job with POST /v1/search.

The Envelope

Every field in a child result.

Endpoints

Account & discovery

Watches

By surface

Parent vs. child ids

Parent response

Child response (the Envelope)

Status values

Polling loop

Errors

Submit a search

The Envelope

​Parent vs. child ids

​Parent response

​Child response (the Envelope)

​Status values

​Polling loop

​Errors

Submit a search

The Envelope

Parent vs. child ids

Parent response

Child response (the Envelope)

Status values

Polling loop

Errors