Get a search

GET

{id}

Get a search

curl --request GET \
  --url https://api.thred.dev/search/{id} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.thred.dev/search/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "search_6c479a30-cf06-4dba-8dc9-2d2893bbc64f",
  "query": "Where can I buy a Nintendo Switch 2 in Austin today?",
  "status": "completed",
  "environment": "development",
  "identity": {
    "name": "AI assistant"
  },
  "call_reason": "public",
  "requested_calls": 2,
  "selected_businesses": 2,
  "attempted_calls": 2,
  "answered_calls": 2,
  "published_results": 2,
  "discovery_shortfall": 0,
  "created_at": "2026-11-12T15:00:00Z",
  "deadline_at": "2026-11-12T15:30:00Z",
  "finished_at": "2026-11-12T15:03:10Z",
  "terminal": true,
  "cancellation_requested": false,
  "stop_reason": null,
  "error": null
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

Read a search’s status and progress using the id returned at creation. completed means processing has finished. Read the answers from Get search results; results are also available while the search is running.

Authorizations

Authorization

string

header

required

Send Authorization: Bearer <THRED_API_KEY>. Development keys begin thr_dev_; Production keys begin thr_prod_. Each key is scoped to a workspace and environment. Keep secrets on your server.

Path Parameters

string

required

Search ID returned by POST /search.

Pattern: ^search_[a-z0-9-]+$

Response

Current search status and progress counters.

string

required

Search ID returned when the request was accepted.

Pattern: ^search_[a-z0-9-]+$

Example:

"search_6c479a30-cf06-4dba-8dc9-2d2893bbc64f"

query

string

required

Example:

"Where can I buy a Nintendo Switch 2 in Austin today?"

status

enum<string>

required

Current search state. completed, failed, canceled, and expired are terminal.

Available options:

discovering,

running,

canceling,

completed,

failed,

canceled,

expired

environment

enum<string>

required

Available options:

development,

production

identity

object

required

Show child attributes

call_reason

enum<string>

required

Available options:

public,

customer

requested_calls

integer

required

The call-attempt limit supplied in the request results field.

Required range: 1 <= x <= 100

selected_businesses

integer

required

Number of selected sources.

Required range: x >= 0

attempted_calls

integer

required

Number of sources where starting a call was attempted.

Required range: x >= 0

answered_calls

integer

required

Calls answered by the destination, including automated answering systems.

Required range: x >= 0

published_results

integer

required

Number of published result entries available from the results endpoint.

Required range: x >= 0

discovery_shortfall

integer | null

required

Requested calls minus selected sources, bounded at zero. Null until source selection has finished.

Required range: x >= 0

created_at

string<date-time>

required

deadline_at

string<date-time>

required

New dialing stops after 30 minutes. Active calls are canceled; post-call processing may finish later.

finished_at

string<date-time> | null

required

When the search reached a terminal state; null while work is in progress.

terminal

boolean

required

Whether all work has settled and no more results will be published.

cancellation_requested

boolean

required

Whether cancellation was requested for this search.

stop_reason

string | null

required

Reason work was stopped early, when present; null for normal completion.

error

object | null

required

Search-level failure details, or null when no search-level error was recorded.

Show child attributes

Get a search

curl --request GET \
  --url https://api.thred.dev/search/{id} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.thred.dev/search/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "search_6c479a30-cf06-4dba-8dc9-2d2893bbc64f",
  "query": "Where can I buy a Nintendo Switch 2 in Austin today?",
  "status": "completed",
  "environment": "development",
  "identity": {
    "name": "AI assistant"
  },
  "call_reason": "public",
  "requested_calls": 2,
  "selected_businesses": 2,
  "attempted_calls": 2,
  "answered_calls": 2,
  "published_results": 2,
  "discovery_shortfall": 0,
  "created_at": "2026-11-12T15:00:00Z",
  "deadline_at": "2026-11-12T15:30:00Z",
  "finished_at": "2026-11-12T15:03:10Z",
  "terminal": true,
  "cancellation_requested": false,
  "stop_reason": null,
  "error": null
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

Get started

Search API

Guides

Account and utilities

Get a search

Authorizations

Path Parameters

Response