discovery-runs

Start a discovery run

Changed on

Start an Atlas discovery pipeline run for a place and set of issue areas.

Use this discovery operation to create, synchronize, lease, inspect, or cancel research work. Treat discovered actors as reviewable leads until their source evidence and visibility state are checked.

Starting a run creates asynchronous research work. Poll the run, then review sources and visibility receipts before using discovered actors in a public or high-stakes workflow.

post/api/discovery-runs

Request

  • Base URL: https://atlas.rebuildingus.org
  • URL: https://atlas.rebuildingus.org/api/discovery-runs
  • Auth: none declared

Headers

x-api-keystring nullable

Request body

direct_urlsstring[]

Seed URLs for direct-URL worker runs that do not require search credentials.

execution_mode'search' | 'direct_url'

How queued Scout workers should execute the discovery run.

issue_areasstring[] required

Issue area slugs that define the run.

location_querystring required

Location query (for example, 'Kansas City, MO').

research_goal'landscape_scan' | 'interview_leads' | 'partner_scan' | 'ecosystem_map'

The research job this run is meant to support.

search_depthstring

Discovery depth hint used by the runner.

statestring required

2-letter state code.

Example request

{
  "execution_mode": "search",
  "issue_areas": [
    "worker_cooperatives",
    "housing_affordability",
    "local_government_and_civic_engagement"
  ],
  "location_query": "Kansas City, MO",
  "research_goal": "landscape_scan",
  "search_depth": "standard",
  "state": "MO"
}

Response

The accepted discovery run.

completed_atstring nullable

Completion timestamp

created_atstring required

Creation timestamp

entries_after_dedupinteger required

Entries after deduplication

entries_confirmedinteger required

Entries confirmed

entries_extractedinteger required

Entries extracted

error_messagestring nullable

Error message if failed

idstring required

Discovery run ID

issue_areasstring[] required

Issue areas queried

location_querystring required

Location query

queries_generatedinteger required

Search queries generated

research_goal'landscape_scan' | 'interview_leads' | 'partner_scan' | 'ecosystem_map' required

Research job this run supports

sources_fetchedinteger required

Sources fetched

sources_processedinteger required

Sources processed

started_atstring required

Start timestamp

statestring required

State code

statusstring required

Status (running, completed, failed)

Example response

{
  "completed_at": "2026-01-15T12:30:00+00:00",
  "created_at": "2026-01-15T10:00:00+00:00",
  "entries_after_dedup": 35,
  "entries_confirmed": 30,
  "entries_extracted": 38,
  "id": "550e8400-e29b-41d4-a716-446655440002",
  "issue_areas": [
    "worker_cooperatives",
    "housing_affordability"
  ],
  "location_query": "Kansas City, MO",
  "queries_generated": 150,
  "research_goal": "landscape_scan",
  "research_summary": {
    "brief": "Three source-backed housing leads in Kansas City.",
    "gaps": [],
    "key_sources": [],
    "ranked_leads": [],
    "reasoning_signals": []
  },
  "sources_fetched": 45,
  "sources_processed": 42,
  "started_at": "2026-01-15T10:00:00+00:00",
  "state": "MO",
  "status": "completed"
}

Changes

  • c604ae765814Revision changes
    • info

      the request property's minLength was decreased from 1 to 0

    • info

      the request property's minLength was decreased from 2 to 0

  • 6ea72ce93d40Revision changes
    • warning

      deleted the header request parameter x-atlas-actor-email

    • warning

      deleted the header request parameter x-atlas-actor-id

    • warning

      deleted the header request parameter x-atlas-internal-secret

    • warning

      deleted the header request parameter x-atlas-organization-id