Research Jobs

1. Add your LLM key

Add a provider key (OpenAI, Anthropic, OpenRouter, Groq and others) in the BYOK section of your dashboard settings. Without one, POST /api/v1/research returns 400 byok_key_required before anything is stored or charged. Pass provider and model in the request to pick a specific key and model.

2. Start a job with a budget

import requests

job = requests.post(
    "https://api.alterlab.io/api/v1/research",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "query": "Which open source vector databases support filtered search?",
        "effort": "deep",
        "max_cost_microcents": 50000,  # cap on platform spend (50,000 microcents)
        "max_sources": 30,
    },
).json()
print(job["id"], job["status"], job["budget"])

Choose effort from lite to frontier; your own caps can only lower the tier caps. When a cap is hit the job finishes as completed_partial and coverage tells you what was not read. See the tier table.

3. Review the plan first

Set plan_first: true to hold the job in awaiting_approval. Nothing is spent until you approve.

base = "https://api.alterlab.io/api/v1/research"
headers = {"X-API-Key": "YOUR_API_KEY"}

plan = requests.get(f"{base}/{job['id']}/plan", headers=headers).json()
# edit the plan, then approve (optionally passing the refined plan)
requests.post(f"{base}/{job['id']}/approve", headers=headers, json={"plan": plan})

4. Follow progress

Poll GET /api/v1/research/{id} until the status is completed, completed_partial, failed or cancelled, or stream /events. If the stream drops, reconnect with Last-Event-ID and you receive only the missed events.

curl -N https://api.alterlab.io/api/v1/research/JOB_ID/events \
  -H "X-API-Key: YOUR_API_KEY"

5. Get a webhook

Pass webhook: { url } (HTTPS) at creation. The signing secret is returned once in the create response. Verify X-AlterLab-Signature as described in the API reference.

Cost control