> ## Documentation Index
> Fetch the complete documentation index at: https://atlas.rebuildingus.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Run discovery and review results

> Use hosted discovery or Scout sync without treating unfinished evidence as verified data.

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

<Note>
  Discovery runs require authentication and plan access. See
  [authentication](/docs/api/authentication) and [rate limits](/docs/api/rate-limits).
</Note>

For exact request and response shapes, use the
[API reference](/docs/api/reference).

## Choose hosted discovery or Scout

| Need                                          | Better path                  |
| --------------------------------------------- | ---------------------------- |
| Start a managed research run from Atlas       | Hosted discovery run         |
| Inspect local research results before syncing | [Scout CLI](/docs/scout/overview) |
| Keep records private until reviewed           | Workspace sync               |
| Publish public-safe records with evidence     | Review, then publish         |

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.

```bash theme={null}
curl -X POST https://atlas.rebuildingus.org/api/discovery-runs \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "location": "Kansas City, MO",
    "issue_areas": ["housing_affordability", "union_organizing"]
  }'
```

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.

```bash theme={null}
curl -H "X-API-Key: your-api-key" \
  "https://atlas.rebuildingus.org/api/discovery-runs/{run_id}"
```

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](/docs/scout/overview) for installation, setup, local runs, and
worker mode.

<Note>
  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.
</Note>

To disable the browser fallback:

```bash theme={null}
scout config set scraper.browser_fallback_enabled false
```

To inspect the active limits:

```bash theme={null}
scout config show
```

The safe workflow is:

<Steps>
  <Step title="Run Scout locally">
    Keep the local results and source evidence for review.
  </Step>

  <Step title="Decide visibility">
    Separate public-safe records from private leads, skipped records, and items
    that need review.
  </Step>

  <Step title="Sync selected results">
    Sync the reviewed result to Atlas.

    ```bash theme={null}
    curl -X POST https://atlas.rebuildingus.org/api/discovery-runs/syncs \
      -H "X-API-Key: your-api-key" \
      -H "Content-Type: application/json" \
      -d @scout-sync.json
    ```
  </Step>

  <Step title="Open the workspace run">
    Use the returned run id and links to continue review in the Atlas workspace.
  </Step>
</Steps>

## 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

<CardGroup cols={2}>
  <Card title="Workspace visibility" icon="lock" href="/docs/api/guides/workspace">
    Keep private review state separate from public records.
  </Card>

  <Card title="Find source-backed actors" icon="users" href="/docs/api/guides/entities">
    Query and inspect the actors discovery found.
  </Card>

  <Card title="Research a city with MCP" icon="robot" href="/docs/mcp/tutorials/research-city">
    Use assistant workflows for the same source-review pattern.
  </Card>

  <Card title="Scout CLI" icon="terminal" href="/docs/scout/overview">
    Run local discovery, inspect evidence, and sync reviewed runs.
  </Card>
</CardGroup>