---
title: "Get a job’s status and result"
method: GET
path: "/v1/jobs/{id}"
---

# Get a job’s status and result

`GET /v1/jobs/{id}`

## Request

- Base URL: `https://api.typesearch.ai`
- URL: `https://api.typesearch.ai/v1/jobs/{id}`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

## Path parameters

- `id` string, required

## Response `200`

The job.

- Job
  - `id` string, required
  - `object` 'job', required
  - `status` 'queued' | 'running' | 'succeeded' | 'failed', required
  - `created_at` string, required
  - `finished_at` string, nullable, required
  - `result` object, nullable, required
    - `id` string, required
    - `object` 'search' | 'site_search' | 'similar', required
    - `mode` 'ultra' | 'fast' | 'normal' | 'deep', required
    - `queries` string[], required
    - `found` boolean, required
    - `total` integer, required
    - `results` object[], required
      - `url` string, required
      - `title` string, required
      - `source` string, nullable, required
      - `country` string, nullable, required: Country of the source (ISO 3166-1 alpha-2), when known.
      - `language` string, nullable, required: Language of the source (ISO 639-1), when known: for a source in several languages, the one asked for in `languages`, or its main one.
      - `published_at` string, nullable, required
      - `section` string, nullable, required
      - `snippet` string, nullable, required: The standfirst or description, as the outlet published it.
      - `score` number, required: Probability that the article is about the query: from reading it if it was read, otherwise from its headline.
      - `headline_relevance` number, required
      - `read` object, nullable, required
        - `probability` number, required
        - `centrality` number, required: 0 not mentioned · 3 main topic.
      - `highlights` string[], required
      - `tone` object, nullable, required
        - `label` 'positive' | 'neutral' | 'negative', required
        - `probabilities` object, required
        - `basis` 'article' | 'headline', required
      - `answers` object, nullable, required
        - `basis` 'article' | 'headline', required
        - `values` object, required
      - `duplicates` object[], required
        - `url` string, required
        - `title` string, required
        - `source` string, nullable, required
      - `date_match` 'exact' | 'adjacent' | 'unknown' | 'outside', nullable, required: When the query names a date: whether the article is about that day (exact), the day before or after (adjacent), cannot tell (unknown) or another date (outside). Null otherwise.
      - `referenced_date` string, nullable, required: When the query names a date: the day the article is about (YYYY-MM-DD, in the request time zone), from its headline, its publication date or reading it.
      - `found_in` 'index' | 'homepage' | 'section' | 'site_search' | 'discovery' | 'custom_index', required: Where it was found: the index; a live site (homepage, section, site_search); discovery, a source beyond the index read at the original site for this request; or custom_index, your own index (`index`).
      - `data` object, nullable: Custom index: the structured data the page declares about itself (schema.org and Open Graph): price, high_price, currency, availability, brand, sku, gtin, rating, reviews. Null if it declares none.
      - `queries` string[]: With several queries: which ones this result belongs to.
    - `groups` object[], nullable, required: With several queries: the breakdown for each one.
      - `query` string, required
      - `found` boolean, required
      - `total` integer, required
      - `results` object[], required
        - `url` string, required
        - `title` string, required
        - `source` string, nullable, required
        - `country` string, nullable, required: Country of the source (ISO 3166-1 alpha-2), when known.
        - `language` string, nullable, required: Language of the source (ISO 639-1), when known: for a source in several languages, the one asked for in `languages`, or its main one.
        - `published_at` string, nullable, required
        - `section` string, nullable, required
        - `snippet` string, nullable, required: The standfirst or description, as the outlet published it.
        - `score` number, required: Probability that the article is about the query: from reading it if it was read, otherwise from its headline.
        - `headline_relevance` number, required
        - `read` object, nullable, required
          - `probability` number, required
          - `centrality` number, required: 0 not mentioned · 3 main topic.
        - `highlights` string[], required
        - `tone` object, nullable, required
          - `label` 'positive' | 'neutral' | 'negative', required
          - `probabilities` object, required
          - `basis` 'article' | 'headline', required
        - `answers` object, nullable, required
          - `basis` 'article' | 'headline', required
          - `values` object, required
        - `duplicates` object[], required
          - `url` string, required
          - `title` string, required
          - `source` string, nullable, required
        - `date_match` 'exact' | 'adjacent' | 'unknown' | 'outside', nullable, required: When the query names a date: whether the article is about that day (exact), the day before or after (adjacent), cannot tell (unknown) or another date (outside). Null otherwise.
        - `referenced_date` string, nullable, required: When the query names a date: the day the article is about (YYYY-MM-DD, in the request time zone), from its headline, its publication date or reading it.
        - `found_in` 'index' | 'homepage' | 'section' | 'site_search' | 'discovery' | 'custom_index', required: Where it was found: the index; a live site (homepage, section, site_search); discovery, a source beyond the index read at the original site for this request; or custom_index, your own index (`index`).
        - `data` object, nullable: Custom index: the structured data the page declares about itself (schema.org and Open Graph): price, high_price, currency, availability, brand, sku, gtin, rating, reviews. Null if it declares none.
        - `queries` string[]: With several queries: which ones this result belongs to.
      - `near_misses` object[], required
        - `url` string, required
        - `title` string, required
        - `source` string, nullable, required
        - `country` string, nullable, required: Country of the source (ISO 3166-1 alpha-2), when known.
        - `language` string, nullable, required: Language of the source (ISO 639-1), when known: for a source in several languages, the one asked for in `languages`, or its main one.
        - `published_at` string, nullable, required
        - `section` string, nullable, required
        - `snippet` string, nullable, required: The standfirst or description, as the outlet published it.
        - `score` number, required: Probability that the article is about the query: from reading it if it was read, otherwise from its headline.
        - `headline_relevance` number, required
        - `read` object, nullable, required
          - `probability` number, required
          - `centrality` number, required: 0 not mentioned · 3 main topic.
        - `highlights` string[], required
        - `tone` object, nullable, required
          - `label` 'positive' | 'neutral' | 'negative', required
          - `probabilities` object, required
          - `basis` 'article' | 'headline', required
        - `answers` object, nullable, required
          - `basis` 'article' | 'headline', required
          - `values` object, required
        - `duplicates` object[], required
          - `url` string, required
          - `title` string, required
          - `source` string, nullable, required
        - `date_match` 'exact' | 'adjacent' | 'unknown' | 'outside', nullable, required: When the query names a date: whether the article is about that day (exact), the day before or after (adjacent), cannot tell (unknown) or another date (outside). Null otherwise.
        - `referenced_date` string, nullable, required: When the query names a date: the day the article is about (YYYY-MM-DD, in the request time zone), from its headline, its publication date or reading it.
        - `found_in` 'index' | 'homepage' | 'section' | 'site_search' | 'discovery' | 'custom_index', required: Where it was found: the index; a live site (homepage, section, site_search); discovery, a source beyond the index read at the original site for this request; or custom_index, your own index (`index`).
        - `data` object, nullable: Custom index: the structured data the page declares about itself (schema.org and Open Graph): price, high_price, currency, availability, brand, sku, gtin, rating, reviews. Null if it declares none.
        - `queries` string[]: With several queries: which ones this result belongs to.
      - `rejected` object[], required
        - `url` string, required
        - `title` string, required
        - `source` string, nullable, required
        - `country` string, nullable, required: Country of the source (ISO 3166-1 alpha-2), when known.
        - `language` string, nullable, required: Language of the source (ISO 639-1), when known: for a source in several languages, the one asked for in `languages`, or its main one.
        - `published_at` string, nullable, required
        - `section` string, nullable, required
        - `snippet` string, nullable, required: The standfirst or description, as the outlet published it.
        - `score` number, required: Probability that the article is about the query: from reading it if it was read, otherwise from its headline.
        - `headline_relevance` number, required
        - `read` object, nullable, required
          - `probability` number, required
          - `centrality` number, required: 0 not mentioned · 3 main topic.
        - `highlights` string[], required
        - `tone` object, nullable, required
          - `label` 'positive' | 'neutral' | 'negative', required
          - `probabilities` object, required
          - `basis` 'article' | 'headline', required
        - `answers` object, nullable, required
          - `basis` 'article' | 'headline', required
          - `values` object, required
        - `duplicates` object[], required
          - `url` string, required
          - `title` string, required
          - `source` string, nullable, required
        - `date_match` 'exact' | 'adjacent' | 'unknown' | 'outside', nullable, required: When the query names a date: whether the article is about that day (exact), the day before or after (adjacent), cannot tell (unknown) or another date (outside). Null otherwise.
        - `referenced_date` string, nullable, required: When the query names a date: the day the article is about (YYYY-MM-DD, in the request time zone), from its headline, its publication date or reading it.
        - `found_in` 'index' | 'homepage' | 'section' | 'site_search' | 'discovery' | 'custom_index', required: Where it was found: the index; a live site (homepage, section, site_search); discovery, a source beyond the index read at the original site for this request; or custom_index, your own index (`index`).
        - `data` object, nullable: Custom index: the structured data the page declares about itself (schema.org and Open Graph): price, high_price, currency, availability, brand, sku, gtin, rating, reviews. Null if it declares none.
        - `queries` string[]: With several queries: which ones this result belongs to.
      - `diffusion` object, nullable, required
        - `by_day` object[], required
          - `day` string, required
          - `count` integer, required
        - `by_source` object[], required
          - `source` string, required
          - `count` integer, required
          - `first_published_at` string, required
        - `first` object, nullable, required
          - `source` string, nullable, required
          - `url` string, required
          - `title` string, required
          - `published_at` string, required
        - `undated` integer, required
      - `tone` object, nullable, required
        - `articles` integer, required
        - `overall` object, required
          - `positive` integer, required
          - `neutral` integer, required
          - `negative` integer, required
        - `by_source` object[], required
          - `positive` integer, required
          - `neutral` integer, required
          - `negative` integer, required
          - `source` string, required
      - `essential` object, nullable, required
        - `excerpts` object[], required
          - `text` string, required
          - `url` string, required
          - `source` string, nullable, required
          - `title` string, required
      - `temporal` object, nullable, required: How the date in the query was read: the topic was judged without it, and the results from that day go first. Null when the query names none.
        - `expression` string, nullable, required: The date words in the query, such as «hoy»; null when the query asks for the latest without naming a date.
        - `from` string, nullable, required: First day of the period the query refers to (YYYY-MM-DD, in `timezone`).
        - `to` string, nullable, required: Last day of that period; the same as `from` for a single day.
        - `timezone` string, required
        - `basis` 'published' | 'event' | 'recency', required: published: what was published about that day · event: news about what is scheduled for that day (published before it) · recency: the query asks for the latest without naming a date, so the newest go first.
        - `window` object, nullable, required: The publication window the date set, when it did. Null when published_after/before (or days) in the request took precedence: then the date only sorts.
          - `from` string, required
          - `to` string, required
        - `widened` boolean, required: No result is from the requested day: they come from the days around it.
    - `near_misses` object[], required: If nothing was found: the closest matches.
      - `url` string, required
      - `title` string, required
      - `source` string, nullable, required
      - `country` string, nullable, required: Country of the source (ISO 3166-1 alpha-2), when known.
      - `language` string, nullable, required: Language of the source (ISO 639-1), when known: for a source in several languages, the one asked for in `languages`, or its main one.
      - `published_at` string, nullable, required
      - `section` string, nullable, required
      - `snippet` string, nullable, required: The standfirst or description, as the outlet published it.
      - `score` number, required: Probability that the article is about the query: from reading it if it was read, otherwise from its headline.
      - `headline_relevance` number, required
      - `read` object, nullable, required
        - `probability` number, required
        - `centrality` number, required: 0 not mentioned · 3 main topic.
      - `highlights` string[], required
      - `tone` object, nullable, required
        - `label` 'positive' | 'neutral' | 'negative', required
        - `probabilities` object, required
        - `basis` 'article' | 'headline', required
      - `answers` object, nullable, required
        - `basis` 'article' | 'headline', required
        - `values` object, required
      - `duplicates` object[], required
        - `url` string, required
        - `title` string, required
        - `source` string, nullable, required
      - `date_match` 'exact' | 'adjacent' | 'unknown' | 'outside', nullable, required: When the query names a date: whether the article is about that day (exact), the day before or after (adjacent), cannot tell (unknown) or another date (outside). Null otherwise.
      - `referenced_date` string, nullable, required: When the query names a date: the day the article is about (YYYY-MM-DD, in the request time zone), from its headline, its publication date or reading it.
      - `found_in` 'index' | 'homepage' | 'section' | 'site_search' | 'discovery' | 'custom_index', required: Where it was found: the index; a live site (homepage, section, site_search); discovery, a source beyond the index read at the original site for this request; or custom_index, your own index (`index`).
      - `data` object, nullable: Custom index: the structured data the page declares about itself (schema.org and Open Graph): price, high_price, currency, availability, brand, sku, gtin, rating, reviews. Null if it declares none.
      - `queries` string[]: With several queries: which ones this result belongs to.
    - `rejected` object[], required: The headline looked relevant, but reading the article ruled it out.
      - `url` string, required
      - `title` string, required
      - `source` string, nullable, required
      - `country` string, nullable, required: Country of the source (ISO 3166-1 alpha-2), when known.
      - `language` string, nullable, required: Language of the source (ISO 639-1), when known: for a source in several languages, the one asked for in `languages`, or its main one.
      - `published_at` string, nullable, required
      - `section` string, nullable, required
      - `snippet` string, nullable, required: The standfirst or description, as the outlet published it.
      - `score` number, required: Probability that the article is about the query: from reading it if it was read, otherwise from its headline.
      - `headline_relevance` number, required
      - `read` object, nullable, required
        - `probability` number, required
        - `centrality` number, required: 0 not mentioned · 3 main topic.
      - `highlights` string[], required
      - `tone` object, nullable, required
        - `label` 'positive' | 'neutral' | 'negative', required
        - `probabilities` object, required
        - `basis` 'article' | 'headline', required
      - `answers` object, nullable, required
        - `basis` 'article' | 'headline', required
        - `values` object, required
      - `duplicates` object[], required
        - `url` string, required
        - `title` string, required
        - `source` string, nullable, required
      - `date_match` 'exact' | 'adjacent' | 'unknown' | 'outside', nullable, required: When the query names a date: whether the article is about that day (exact), the day before or after (adjacent), cannot tell (unknown) or another date (outside). Null otherwise.
      - `referenced_date` string, nullable, required: When the query names a date: the day the article is about (YYYY-MM-DD, in the request time zone), from its headline, its publication date or reading it.
      - `found_in` 'index' | 'homepage' | 'section' | 'site_search' | 'discovery' | 'custom_index', required: Where it was found: the index; a live site (homepage, section, site_search); discovery, a source beyond the index read at the original site for this request; or custom_index, your own index (`index`).
      - `data` object, nullable: Custom index: the structured data the page declares about itself (schema.org and Open Graph): price, high_price, currency, availability, brand, sku, gtin, rating, reviews. Null if it declares none.
      - `queries` string[]: With several queries: which ones this result belongs to.
    - `diffusion` object, nullable, required
      - `by_day` object[], required
        - `day` string, required
        - `count` integer, required
      - `by_source` object[], required
        - `source` string, required
        - `count` integer, required
        - `first_published_at` string, required
      - `first` object, nullable, required
        - `source` string, nullable, required
        - `url` string, required
        - `title` string, required
        - `published_at` string, required
      - `undated` integer, required
    - `tone` object, nullable, required
      - `articles` integer, required
      - `overall` object, required
        - `positive` integer, required
        - `neutral` integer, required
        - `negative` integer, required
      - `by_source` object[], required
        - `positive` integer, required
        - `neutral` integer, required
        - `negative` integer, required
        - `source` string, required
    - `essential` object, nullable, required
      - `excerpts` object[], required
        - `text` string, required
        - `url` string, required
        - `source` string, nullable, required
        - `title` string, required
    - `reference` object, nullable, required
      - `url` string, required
      - `title` string, required
    - `custom_index` object, nullable: With `index`: the custom index that was searched.
      - `id` string, required
      - `name` string, required
    - `temporal` object, nullable, required: How the date in the query was read: the topic was judged without it, and the results from that day go first. Null when the query names none.
      - `expression` string, nullable, required: The date words in the query, such as «hoy»; null when the query asks for the latest without naming a date.
      - `from` string, nullable, required: First day of the period the query refers to (YYYY-MM-DD, in `timezone`).
      - `to` string, nullable, required: Last day of that period; the same as `from` for a single day.
      - `timezone` string, required
      - `basis` 'published' | 'event' | 'recency', required: published: what was published about that day · event: news about what is scheduled for that day (published before it) · recency: the query asks for the latest without naming a date, so the newest go first.
      - `window` object, nullable, required: The publication window the date set, when it did. Null when published_after/before (or days) in the request took precedence: then the date only sorts.
        - `from` string, required
        - `to` string, required
      - `widened` boolean, required: No result is from the requested day: they come from the days around it.
    - `site` string, nullable, required
    - `index` object, nullable, required
      - `updated_at` string, nullable, required: The oldest last refresh among the sources searched: how fresh the index was for this request.
    - `usage` object, required
      - `tokens` integer, required: Model tokens used by this request. 0 when it came from the cache.
      - `calls` integer, required
      - `cost_usd` number, nullable, required: What this request was billed, in USD: the list price of its mode (see `pricing` in GET /v1/usage), per query. 0 when it came from the cache. Null in partial results.
      - `headlines` integer, required
      - `from_memory` integer, required
      - `pages_direct` integer, required
      - `pages_browser` integer, required
      - `duration_ms` integer, required
    - `budget` object, nullable, required
      - `max_tokens` integer, required
      - `used` integer, required
      - `exhausted` boolean, required
    - `discovery` object, nullable, required: Discovery: when the index has fewer than 3 good matches, typesearch looks for sources beyond it and reads them at the original site. Null only in partial events, while it is still running.
      - `status` 'used' | 'background' | 'skipped' | 'budget' | 'timeout', required: used: it searched beyond the index within the time budget · background: in ultra or fast there was nothing to check quickly; it keeps learning in the background · skipped: the index had enough, or it does not apply · budget: the discovery limit was reached · timeout: the time budget ran out (incomplete: true).
      - `sites` integer, required: Sites beyond the index that contributed candidates.
      - `ms` integer, required: Time it added to this request, in milliseconds.
    - `incomplete` boolean, required: The token cap (max_tokens) or the discovery time budget ran out: there may be more.
    - `cached_at` string, nullable, required
    - `warnings` object[], required
      - `code` string, required
      - `message` string, required
  - `error` object, nullable, required
    - `type` string, required
    - `title` string, required
    - `status` integer, required
    - `detail` string, required
    - `code` string, required
    - `request_id` string, required
    - `errors` object[]
      - `path` string, required
      - `message` string, required

## Other responses

- `402`: Payment required: `insufficient_credits` (no credit left), `spend_limit_reached` (the key hit its monthly limit) or `budget_too_small`.
- `default`: Error (RFC 9457). In English unless the request sends `Accept-Language: es`.

---

[API](https://skmtc.dev/typesearch/apis/typesearch-news-search-api.md) · [All operations](https://skmtc.dev/typesearch/apis/typesearch-news-search-api/llms.txt) · [OpenAPI document](https://skmtc.dev/typesearch/apis/typesearch-news-search-api/revisions/b270b9a9c6a5?raw)