Skip to main content

​
Overview

Discovery helps a team find public sources, extract candidate civic actors, and turn the results into reviewable Atlas records. Use discovery when normal search is not enough: a place has thin coverage, a team needs a focused research pass, or Scout has produced local evidence that should be synced into a workspace.
Discovery runs require authentication and plan access. See authentication and rate limits.
For exact request and response shapes, use the API reference.

​
Choose hosted discovery or Scout

Hosted discovery is simpler. Scout is better when the team needs a local, inspectable research process before deciding what belongs in Atlas.

​
Start a hosted run

Discovery runs are asynchronous. The API accepts the request, returns a run id, and processes the work in the background.
Store the run id. The run id is the handle for status checks, workspace review, and later evidence review.

​
Poll without turning it into a crawler

Poll a pending or running discovery run with a modest interval. Stop polling when the run completes or fails.
Completion means the pipeline finished. It does not mean every result is ready for publication, outreach, funding review, or import.

​
Review before using results

After a run completes, review:
  • Which results are people, organizations, initiatives, campaigns, or events.
  • Which source supports each claim.
  • Whether source dates are recent enough.
  • Whether the same actor appears in multiple independent sources.
  • Which issue areas are well-covered and which remain thin.
  • Which records should stay private until a human checks them.
A discovery run should make the review path easier. It should not remove review.

​
Sync Scout results

Scout is useful when a researcher wants local control over queries, cache, source review, or iterative deepening before syncing selected results. Read the Scout CLI guide for installation, setup, local runs, and worker mode.
Scout may launch a headless Chromium browser through Playwright when a public source looks useful but normal HTML fetching cannot read enough text. This is a bounded fallback for JavaScript-rendered pages, not the primary fetch path: Scout fetches ordinary HTML first, defaults to 8 browser render attempts per run, and keeps browser rendering serial by default. It does not open visible browser windows.
To disable the browser fallback:
To inspect the active limits:
The safe workflow is:
1

Run Scout locally

Keep the local results and source evidence for review.
2

Decide visibility

Separate public-safe records from private leads, skipped records, and items that need review.
3

Sync selected results

Sync the reviewed result to Atlas.
4

Open the workspace run

Use the returned run id and links to continue review in the Atlas workspace.

​
Use sync receipts

Sync receipts are there to protect trust at the boundary between local research, workspace data, and public directory records. Look for:
  • Remote run id.
  • Local-to-remote entry links.
  • Visibility state.
  • Review state.
  • Workspace links for briefs, lists, or coverage targets.
Treat links as mappings, not proof. The sources determine whether a result is strong enough to use.

​
Next steps

Workspace visibility

Keep private review state separate from public records.

Find source-backed actors

Query and inspect the actors discovery found.

Research a city with MCP

Use assistant workflows for the same source-review pattern.

Scout CLI

Run local discovery, inspect evidence, and sync reviewed runs.