```yaml
product: AlterLab
title: Research Jobs
category: guides
comparison_context: "AlterLab is an alternative to Firecrawl, ScrapingBee, and Bright Data."
source_url: https://alterlab.io/docs/guides/research
```

# Research Jobs

A research job searches, reads sources and writes a cited answer while staying inside a budget you choose. The model calls run on your own key.

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

```python
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 in the Research API reference (`/docs/api/research`).

## 3. Review the plan first

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

```python
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.

```bash
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 Research API reference (`/docs/api/research#webhooks`).

## Cost control

Each search a job runs costs $0.001. Page fetches are priced per step at the scrape tier of the URL, and the running total is in `cost.platform_microcents`. Model tokens are billed by your provider, not AlterLab. New accounts get up to 5,000 free requests.