Poll a research brief

Written and maintained by The ProspectAPIs team

GET/v1/research/:id

GET /v1/research/:id is the ProspectAPIs operation getResearch, in the Research group of the REST API. One research job, for its owner only (another account's id reads as not found). Free. Poll until status is completed (the brief is in result) or failed (the reason is in error, and the charge was refunded). Cost: free, owner only. Send your API key as a Bearer token in the Authorization header.

How this fits with the rest of the research API, with worked examples, is in the prospect research guide.

Parameters

Parameters of GET /v1/research/:id
Name	In	Type	Description
id required	path	string (uuid)	A UUID.

Responses

Response codes of GET /v1/research/:id
Status	Meaning
200	The research job.
400	The request was invalid (e.g. a bad filter or input); nothing was charged.
401	The API key is missing or invalid.
404	No such record for this account.
429	Too many requests; retry after the window.

Every error answers with the same JSON body, an error string and sometimes a code; the errors page lists each status and when it happens. A per-key 429 carries Retry-After; see rate limits.

200 response fields

The research job. The body is a ResearchJob.

Fields of the 200 response
Field	Type	Description
research_id required	string (uuid)
status required	string	queued while it runs, then completed or failed.
input required	object	The normalised input, echoed back.
result required	object or null	The cited brief when status is completed, else null.
error required	object or string or null	Why it failed when status is failed, else null.
created_at required	string (date-time)
completed_at required	string (date-time) or null

Code samples

Each sample sends the same request. Set PROSPECTAPIS_KEY in your environment first. Values come from the spec's examples; replace them with your own.

curl

curl https://api.prospectapis.com/v1/research/3f6c1d2e-8b4a-4f7e-9c21-5a0d7e9b4c13 \
  -H "Authorization: Bearer $PROSPECTAPIS_KEY"

JavaScript (fetch)

const res = await fetch("https://api.prospectapis.com/v1/research/3f6c1d2e-8b4a-4f7e-9c21-5a0d7e9b4c13", {
  headers: { Authorization: `Bearer ${process.env.PROSPECTAPIS_KEY}` },
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json().catch(() => ({}))).error ?? res.statusText}`);
const data = await res.json();
console.log(data);

Python (requests)

import os, requests

res = requests.get(
    "https://api.prospectapis.com/v1/research/3f6c1d2e-8b4a-4f7e-9c21-5a0d7e9b4c13",
    headers={"Authorization": f"Bearer {os.environ['PROSPECTAPIS_KEY']}"},
    timeout=30,
)
res.raise_for_status()
data = res.json()
print(data)

Billing

This call is free: it never spends credits or free records, so you can call it as often as the rate limit allows. Metered calls on the same key report your balance after each response in X-Credits-Remaining, and GET /v1/account shows it at any time.

The prospect research guide covers this area end to end. Previous operation: Start a research brief. Next operation: List watchlists. Every operation, grouped by area, is on the API reference index.

Create a free account to get a key, then run the samples above with your own values.

Was this page helpful?