Skip to main content
POST
Send a query and results count. The API returns HTTP 202 with an id; use it to read the answers. Optional output fields add structured values alongside the text answer. Choose Structured answers in the example menu to see the format. results accepts 1–100 and caps call attempts to distinct sources; the number of complete answers may be smaller.

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.

Body

application/json
query
string
required

The information to obtain. Must contain non-whitespace text. Include location when it matters.

Required string length: 1 - 8000
Pattern: \S
Example:

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

results
integer
required

Hard cap of call attempts to distinct sources. Unanswered calls and negative answers count; successful matches are not guaranteed.

Required range: 1 <= x <= 100
Example:

2

identity
object
call_reason
enum<string>
default:public

Purpose of the call. Public does not make results publicly accessible.

Available options:
public,
customer
location
string

Geographic context for the search.

Required string length: 1 - 300
Pattern: \S
language
string

Language tag such as en or fr-CA.

Pattern: ^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8}){0,3}$
Example:

"en"

output
object

Optional custom fields to collect, at most 20 fields and 12,000 characters of JSON. If omitted, each result contains a concise natural-language answer in content and no output property; Thred does not generate custom fields. Field names must contain 1–120 characters and cannot be __proto__, prototype, or constructor. Descriptions must contain non-whitespace text.

webhook_id
string

An enabled webhook endpoint in the same workspace/environment.

Required string length: 1 - 200
Pattern: \S
metadata
object

Custom metadata stored with the search, up to 4000 UTF-8 bytes of JSON. Defaults to an empty object. It is not echoed in status, results, or webhook payloads.

Response

Search accepted.

id
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
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.