Managed Research Quickstart

1. Create a project

From the Managed Research dashboard, click New project. Set a name, timezone, and initial budget cap.

2. Complete onboarding

The Start run button stays disabled until onboarding is complete. Open the Onboarding tab and work through the four steps:Step 1: Project basics — Name, timezone, schedule window (at New project).Step 2: Connect GitHub — OAuth or PAT with repo scope. Workers use this to clone and push. Optional; you can skip.Step 3: Starting data & spec — Upload datasets, example traces, or other references the agents should use. Write the project spec describing what agents should research.Step 4: Budgets — Set a monthly cap and per-run cap. Both are hard stops — when hit the run stops with stop_reason: budget_exhausted. Set the timebox (max run duration) to cap how long a run can execute.Click Run checks to run the dry-run validation. When it passes, onboarding is complete.

3. Trigger a run

Click Start run from the project dashboard. You can optionally override the agent model (gpt-5.2 is the default), timebox (max run duration), and schedule.The run moves through:

queued → planning → executing → [blocked] → finalizing → done
                                                        ↘ failed / stopped

4. Monitor

Orchestrator status — running, idle, or unhealthy (heartbeat > 5 min stale)
Worker tasks table — one row per task with state and last heartbeat

If a worker needs approval before an action (e.g. pushing a PR), the run moves to blocked. Approve or deny from the dashboard.

5. Inspect outputs

When the run reaches done, open the Deliverables tab:

Artifact type	Contents
`report_md`	Markdown report authored by workers — rendered first
`github_pr`	Pull requests opened on your repo(s) — links with status
Result files	Any other artifacts workers produced — downloadable

6. Check spend

The Usage tab shows MTD spend by provider and funding source, per-run history, and budget remaining.

1. Create a project

curl -X POST https://api.usesynth.ai/smr/projects \
  -H "Authorization: Bearer $SYNTH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-research-project",
    "timezone": "UTC",
    "key_policy": { "mode": "synth_only" },
    "budgets": { "monthly_usd_cents": 5000, "run_usd_cents": 500 }
  }'

Save the returned project_id.

2. Connect GitHub

curl -X POST https://api.usesynth.ai/smr/integrations/github/pat/connect \
  -H "Authorization: Bearer $SYNTH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "<project_id>",
    "token": "<github_pat>"
  }'

3. Complete onboarding steps

# Mark artifact_storage complete (Synth S3 is default, auto-configured)
curl -X POST https://api.usesynth.ai/smr/projects/<project_id>/onboarding/complete_step \
  -H "Authorization: Bearer $SYNTH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"step": "artifact_storage", "status": "complete"}'

# Mark starting_data_spec complete (if you uploaded files/spec via UI, or skip via API)
curl -X POST https://api.usesynth.ai/smr/projects/<project_id>/onboarding/complete_step \
  -H "Authorization: Bearer $SYNTH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"step": "starting_data_spec", "status": "complete"}'

# Set keys + budgets
curl -X PATCH https://api.usesynth.ai/smr/projects/<project_id> \
  -H "Authorization: Bearer $SYNTH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key_policy": { "mode": "synth_only" },
    "budgets": { "monthly_usd_cents": 5000, "run_usd_cents": 500 }
  }'

curl -X POST https://api.usesynth.ai/smr/projects/<project_id>/onboarding/complete_step \
  -H "Authorization: Bearer $SYNTH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"step": "keys_budgets", "status": "complete"}'

4. Run dry-run validation

curl -X POST https://api.usesynth.ai/smr/projects/<project_id>/onboarding/dry_run \
  -H "Authorization: Bearer $SYNTH_API_KEY"

Returns {"result": {"status": "passed"}} when ready.

5. Trigger a run

curl -X POST https://api.usesynth.ai/smr/projects/<project_id>/trigger \
  -H "Authorization: Bearer $SYNTH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "timebox_seconds": 28800,
    "agent_model": "gpt-5.2",
    "agent_kind": "codex"
  }'

agent_kind must be one of codex, claude, or opencode.

6. Poll run state

curl https://api.usesynth.ai/smr/projects/<project_id>/runs/<run_id> \
  -H "Authorization: Bearer $SYNTH_API_KEY"

Poll until state is done, failed, or stopped.

7. Fetch artifacts

# List artifacts for the run
curl https://api.usesynth.ai/smr/projects/<project_id>/runs/<run_id>/artifacts \
  -H "Authorization: Bearer $SYNTH_API_KEY"

# Download a specific artifact
curl https://api.usesynth.ai/smr/artifacts/<artifact_id>/content \
  -H "Authorization: Bearer $SYNTH_API_KEY"

8. Check spend

curl https://api.usesynth.ai/smr/projects/<project_id>/usage \
  -H "Authorization: Bearer $SYNTH_API_KEY"

Returns MTD and last-7-days totals broken down by provider and funding source.

Getting started

Concepts

Managed Research Quickstart

1. Create a project

2. Complete onboarding

3. Trigger a run

4. Monitor

5. Inspect outputs

6. Check spend

1. Create a project

2. Connect GitHub

3. Complete onboarding steps

4. Run dry-run validation

5. Trigger a run

6. Poll run state

7. Fetch artifacts

8. Check spend

Getting started

Concepts

​1. Create a project

​2. Complete onboarding

​3. Trigger a run

​4. Monitor

​5. Inspect outputs

​6. Check spend

​1. Create a project

​2. Connect GitHub

​3. Complete onboarding steps

​4. Run dry-run validation

​5. Trigger a run

​6. Poll run state

​7. Fetch artifacts

​8. Check spend

1. Create a project

2. Complete onboarding

3. Trigger a run

4. Monitor

5. Inspect outputs

6. Check spend

1. Create a project

2. Connect GitHub

3. Complete onboarding steps

4. Run dry-run validation

5. Trigger a run

6. Poll run state

7. Fetch artifacts

8. Check spend