Search Run Get

GET

https://core.usescout.sh/v1/searches/:search_id

GET

/v1/searches/:search_id

$ curl https://core.usescout.sh/v1/searches/search_id \
>      -H "Authorization: Bearer <token>" \
>      -H "Content-Type: application/json"

1 {
2   "search_id": "a1b2c3d4-e5f6-7890-ab12-cd34ef567890",
3   "status": "running",
4   "queries": [
5     "latest advancements in renewable energy"
6   ],
7   "limit": 10,
8   "depth": "deep",
9   "country": "us",
10   "language": "en",
11   "createdAt": "2024-06-01T10:15:30Z",
12   "completedAt": null,
13   "credits": 3,
14   "results": [
15     {
16       "title": "Breakthroughs in Solar Panel Efficiency",
17       "url": "https://example.com/solar-efficiency",
18       "snippet": "Recent studies show a 25% increase in solar panel efficiency using new materials.",
19       "date": "2024-05-30"
20     }
21   ],
22   "pagesFetched": 5,
23   "pagesTarget": 10,
24   "error": null,
25   "report": "## Renewable Energy Research Report\nThe search focused on recent innovations in renewable energy, highlighting solar and wind technologies. [1]\n\n[1]: https://example.com/solar-efficiency",
26   "findings": [
27     {
28       "subquery": "solar panel efficiency",
29       "answer": "Solar panels have improved efficiency by 25% due to new materials.",
30       "citations": [
31         "https://example.com/solar-efficiency"
32       ],
33       "confidence": 0.92,
34       "evidence": "Peer-reviewed journal article published in 2024."
35     }
36   ],
37   "sources": [
38     {
39       "index": 1,
40       "url": "https://example.com/solar-efficiency",
41       "title": "Breakthroughs in Solar Panel Efficiency",
42       "domain": "example.com",
43       "fetched": "2024-06-01T10:00:00Z",
44       "quality": "high",
45       "first_seen_subquery": "solar panel efficiency"
46     }
47   ],
48   "usage": {
49     "planner_calls": 2,
50     "grader_calls": 1,
51     "synth_calls": 1,
52     "search_queries": 3,
53     "pages_fetched": 5,
54     "tokens": 1500
55   },
56   "prompt": "Research recent advancements in renewable energy technologies with a focus on solar and wind power.",
57   "reranked": true
58 }

Poll an async deep-search run; current results are included as they accumulate.

Search Run Get

GET

https://core.usescout.sh/v1/searches/:search_id

GET

/v1/searches/:search_id

$ curl https://core.usescout.sh/v1/searches/search_id \
>      -H "Authorization: Bearer <token>" \
>      -H "Content-Type: application/json"

1 {
2   "search_id": "a1b2c3d4-e5f6-7890-ab12-cd34ef567890",
3   "status": "running",
4   "queries": [
5     "latest advancements in renewable energy"
6   ],
7   "limit": 10,
8   "depth": "deep",
9   "country": "us",
10   "language": "en",
11   "createdAt": "2024-06-01T10:15:30Z",
12   "completedAt": null,
13   "credits": 3,
14   "results": [
15     {
16       "title": "Breakthroughs in Solar Panel Efficiency",
17       "url": "https://example.com/solar-efficiency",
18       "snippet": "Recent studies show a 25% increase in solar panel efficiency using new materials.",
19       "date": "2024-05-30"
20     }
21   ],
22   "pagesFetched": 5,
23   "pagesTarget": 10,
24   "error": null,
25   "report": "## Renewable Energy Research Report\nThe search focused on recent innovations in renewable energy, highlighting solar and wind technologies. [1]\n\n[1]: https://example.com/solar-efficiency",
26   "findings": [
27     {
28       "subquery": "solar panel efficiency",
29       "answer": "Solar panels have improved efficiency by 25% due to new materials.",
30       "citations": [
31         "https://example.com/solar-efficiency"
32       ],
33       "confidence": 0.92,
34       "evidence": "Peer-reviewed journal article published in 2024."
35     }
36   ],
37   "sources": [
38     {
39       "index": 1,
40       "url": "https://example.com/solar-efficiency",
41       "title": "Breakthroughs in Solar Panel Efficiency",
42       "domain": "example.com",
43       "fetched": "2024-06-01T10:00:00Z",
44       "quality": "high",
45       "first_seen_subquery": "solar panel efficiency"
46     }
47   ],
48   "usage": {
49     "planner_calls": 2,
50     "grader_calls": 1,
51     "synth_calls": 1,
52     "search_queries": 3,
53     "pages_fetched": 5,
54     "tokens": 1500
55   },
56   "prompt": "Research recent advancements in renewable energy technologies with a focus on solar and wind power.",
57   "reranked": true
58 }

Poll an async deep-search run; current results are included as they accumulate.

Authentication

AuthorizationBearer

Your API key, sent as a Bearer token.

Path parameters

search_idstringRequired

Response

Successful Response

search_idstring

Opaque run identifier.

statusstring

queued, running, completed, failed or cancelled.

querieslist of strings

The queries being run.

limitinteger

Max merged results to return.

depthstringDefaults to deep

Always deep for async search.

countrystringDefaults to us

Two-letter country code.

languagestringDefaults to en

UI language code.

createdAtstring or null

ISO-8601 creation timestamp.

completedAtstring or null

ISO-8601 completion timestamp.

creditsintegerDefaults to 0

Credits accrued (one per query, on completion).

resultslist of maps from strings to any

Merged, de-duplicated results. Empty until completed.

pagesFetchedintegerDefaults to 0

SERP pages fetched across all queries so far.

pagesTargetintegerDefaults to 1

Target total SERP pages across all queries.

errorstring or null

Failure reason when status is failed.

reportstring or null

Markdown research report with inline [N] citations.

findingslist of maps from strings to any or null

Per-sub_query findings (subquery, answer, citations, confidence, evidence).

sourceslist of maps from strings to any or null

Numbered sources list (index, url, title, domain, fetched, quality, first_seen_subquery).

usagemap from strings to any or null

Research-engine usage stats (planner_calls, grader_calls, synth_calls, search_queries, pages_fetched, tokens).

promptstring or null

The research question, when the engine was invoked with depth=‘deep’ + research-mode controls.

rerankedbooleanDefaults to false

True iff results were re-ranked against objective by a fast LLM pass for this run.

Errors

422

Unprocessable Entity Error

$	curl https://core.usescout.sh/v1/searches/search_id \
>	-H "Authorization: Bearer <token>" \
>	-H "Content-Type: application/json"

1	{
2	"search_id": "a1b2c3d4-e5f6-7890-ab12-cd34ef567890",
3	"status": "running",
4	"queries": [
5	"latest advancements in renewable energy"
6	],
7	"limit": 10,
8	"depth": "deep",
9	"country": "us",
10	"language": "en",
11	"createdAt": "2024-06-01T10:15:30Z",
12	"completedAt": null,
13	"credits": 3,
14	"results": [
15	{
16	"title": "Breakthroughs in Solar Panel Efficiency",
17	"url": "https://example.com/solar-efficiency",
18	"snippet": "Recent studies show a 25% increase in solar panel efficiency using new materials.",
19	"date": "2024-05-30"
20	}
21	],
22	"pagesFetched": 5,
23	"pagesTarget": 10,
24	"error": null,
25	"report": "## Renewable Energy Research Report\nThe search focused on recent innovations in renewable energy, highlighting solar and wind technologies. [1]\n\n[1]: https://example.com/solar-efficiency",
26	"findings": [
27	{
28	"subquery": "solar panel efficiency",
29	"answer": "Solar panels have improved efficiency by 25% due to new materials.",
30	"citations": [
31	"https://example.com/solar-efficiency"
32	],
33	"confidence": 0.92,
34	"evidence": "Peer-reviewed journal article published in 2024."
35	}
36	],
37	"sources": [
38	{
39	"index": 1,
40	"url": "https://example.com/solar-efficiency",
41	"title": "Breakthroughs in Solar Panel Efficiency",
42	"domain": "example.com",
43	"fetched": "2024-06-01T10:00:00Z",
44	"quality": "high",
45	"first_seen_subquery": "solar panel efficiency"
46	}
47	],
48	"usage": {
49	"planner_calls": 2,
50	"grader_calls": 1,
51	"synth_calls": 1,
52	"search_queries": 3,
53	"pages_fetched": 5,
54	"tokens": 1500
55	},
56	"prompt": "Research recent advancements in renewable energy technologies with a focus on solar and wind power.",
57	"reranked": true
58	}