POST

Start a scrape run

https://scrape.usesieve.com/api/scrapes

Queues an agent-driven scrape run. Describe what you want in plain language; optionally pin the exact pages to visit and the columns you expect back. Returns immediately with a session id you poll for results. Also accepts multipart/form-data with a "file" field to extract from an uploaded document.

Request Body

Name	Type	Required	Description
instruction	string	Optional	What to collect, in plain language. Required unless target_urls is provided (then one is synthesized). Alias: prompt
target_urls	string[]	Optional	Public http(s) pages to scrape. Aliases: urls, url. Full URLs inside the instruction text are also picked up automatically
fields	string[]	Optional	Column names you expect in the output table. Alias: columns
schema_hints	object	Optional	Richer output-shape hints (object, list, or string). Alias: schema
compliance_mode	string	Optional	How cautiously to treat target sites: "conservative", "regular" (default), or "yolo"
table_shape	string	Optional	"long" (default) or "wide" output table
sample_run	boolean	Optional	Collect only a small sample first (default false). sample_limit (1-1000, default 25) caps the rows

instructionstringOptional

What to collect, in plain language. Required unless target_urls is provided (then one is synthesized). Alias: prompt

target_urlsstring[]Optional

Public http(s) pages to scrape. Aliases: urls, url. Full URLs inside the instruction text are also picked up automatically

fieldsstring[]Optional

Column names you expect in the output table. Alias: columns

schema_hintsobjectOptional

Richer output-shape hints (object, list, or string). Alias: schema

compliance_modestringOptional

How cautiously to treat target sites: "conservative", "regular" (default), or "yolo"

table_shapestringOptional

"long" (default) or "wide" output table

sample_runbooleanOptional

Collect only a small sample first (default false). sample_limit (1-1000, default 25) caps the rows

Request

curl --request POST \
  --url https://scrape.usesieve.com/api/scrapes \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data '{
  "instruction": "Extract store name, address, phone, and hours",
  "target_urls": [
    "https://example.com/stores"
  ],
  "fields": [
    "name",
    "address",
    "phone",
    "hours"
  ],
  "compliance_mode": "regular"
}'

Response 202

{
  "status": "queued",
  "session_id": "20260709-153000-a1b2c3",
  "poll": "/api/scrapes/20260709-153000-a1b2c3"
}

GET

Get run status & results

https://scrape.usesieve.com/api/scrapes/{session_id}

Polls a run. status is "running" until the current turn finishes, then "done". files lists the deliverables produced so far (CSV/JSON), each with a download url; new_files holds only the latest turn’s output.

URL Parameters

Name	Type	Required	Description
session_id	string	Required	The session id returned by POST /api/scrapes

session_idstringRequired

The session id returned by POST /api/scrapes

Request

curl --request GET \
  --url https://scrape.usesieve.com/api/scrapes/{session_id} \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Response 200

{
  "status": "done",
  "turns": 1,
  "last_turn_at": "2026-07-09T15:34:12Z",
  "summary": "Collected 42 store locations into scrape_results.csv",
  "files": [
    {
      "name": "scrape_results.csv",
      "size": 18244,
      "ext": "csv",
      "url": "/api/sessions/20260709-153000-a1b2c3/files/scrape_results.csv?download=1"
    }
  ]
}

POST

Send a follow-up instruction

https://scrape.usesieve.com/api/scrapes/{session_id}/messages

Continues an existing run with another instruction — refine the extraction, add columns, or point the agent at more pages. Same body as starting a run. Returns 409 if a turn is still in progress.

URL Parameters

Name	Type	Required	Description
session_id	string	Required	The session to continue

session_idstringRequired

The session to continue

Request Body

Name	Type	Required	Description
instruction	string	Required	The follow-up request, in plain language

instructionstringRequired

The follow-up request, in plain language

Request

curl --request POST \
  --url https://scrape.usesieve.com/api/scrapes/{session_id}/messages \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data '{
  "instruction": "Also capture each store’s email address, and drop closed locations"
}'

Response 202

{
  "status": "queued",
  "session_id": "20260709-153000-a1b2c3",
  "poll": "/api/scrapes/20260709-153000-a1b2c3"
}

POST

Create a monitor from a run

https://scrape.usesieve.com/api/scrapes/{session_id}/monitor

Turns a finished scrape into a recurring monitor. Either describe the schedule and alerts in plain language via instruction, or set the structured fields directly. Runs re-scrape on schedule and notify you on change by email, Slack, or webhook.

URL Parameters

Name	Type	Required	Description
session_id	string	Required	A session whose scrape you want to re-run on a schedule

session_idstringRequired

A session whose scrape you want to re-run on a schedule

Request Body

Name	Type	Required	Description
instruction	string	Optional	Plain-language setup, e.g. "check daily at 9am and email me when rows change". Required if no structured fields are set
name	string	Optional	Display name for the monitor
schedule_kind	string	Optional	interval \| hourly \| daily \| weekly \| monthly \| on-demand
schedule_time	string	Optional	HH:MM time of day for daily/weekly/monthly schedules
email_recipients	string[]	Optional	Who to email when the monitor fires
webhook_url	string	Optional	URL that receives JSON events (monitor.changed, monitor.failed, ...) after each run
notify_only_if_changed	boolean	Optional	Alert only when the scraped data actually changed

instructionstringOptional

Plain-language setup, e.g. "check daily at 9am and email me when rows change". Required if no structured fields are set

namestringOptional

Display name for the monitor

schedule_kindstringOptional

schedule_timestringOptional

HH:MM time of day for daily/weekly/monthly schedules

email_recipientsstring[]Optional

Who to email when the monitor fires

webhook_urlstringOptional

URL that receives JSON events (monitor.changed, monitor.failed, ...) after each run

notify_only_if_changedbooleanOptional

Alert only when the scraped data actually changed

Request

curl --request POST \
  --url https://scrape.usesieve.com/api/scrapes/{session_id}/monitor \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data '{
  "instruction": "Re-check every day at 09:00 and email me only when something changes",
  "email_recipients": [
    "analyst@example.com"
  ]
}'

Response 202

{
  "status": "queued",
  "session_id": "20260709-153000-a1b2c3",
  "poll": "/api/scrapes/20260709-153000-a1b2c3",
  "monitors": "/api/sessions/20260709-153000-a1b2c3/monitors"
}

GET

List your monitors

https://scrape.usesieve.com/api/monitors?mine=1

Lists the monitors owned by the API key’s account, with their schedules and notification settings.

Request

curl --request GET \
  --url https://scrape.usesieve.com/api/monitors?mine=1 \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Response 200

{
  "monitors": [
    {
      "id": "mon_8f3a2c",
      "name": "Competitor pricing page",
      "schedule_kind": "daily",
      "schedule_time": "09:00",
      "notify_only_if_changed": true
    }
  ]
}

POST

Trigger a monitor run

https://scrape.usesieve.com/api/monitors/{monitor_id}/runs

Kicks off a run now (async). Returns 202 with a run id to poll; 402 if the account is out of credits. Run status ends at changed, no_change, or failed.

URL Parameters

Name	Type	Required	Description
monitor_id	string	Required	The monitor to run

monitor_idstringRequired

The monitor to run

Request

curl --request POST \
  --url https://scrape.usesieve.com/api/monitors/{monitor_id}/runs \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Response 202

{
  "monitor_id": "mon_8f3a2c",
  "run_id": "run_20260709-1600",
  "status": "running",
  "already_running": false,
  "poll": "/api/monitors/mon_8f3a2c/runs/run_20260709-1600",
  "results": "/api/monitors/mon_8f3a2c/runs/run_20260709-1600/results"
}

GET

Get run results

https://scrape.usesieve.com/api/monitors/{monitor_id}/runs/{run_id}/results

Returns the scraped table for a run, plus the diff against the previous run. Use the literal run id "latest" for the most recent run.

URL Parameters

Name	Type	Required	Description
monitor_id	string	Required	The monitor
run_id	string	Required	A run id, or "latest"

monitor_idstringRequired

The monitor

run_idstringRequired

A run id, or "latest"

Request

curl --request GET \
  --url https://scrape.usesieve.com/api/monitors/{monitor_id}/runs/{run_id}/results \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Response 200

{
  "monitor_id": "mon_8f3a2c",
  "run_id": "run_20260709-1600",
  "columns": [
    "name",
    "price"
  ],
  "rows": [
    [
      "Team plan",
      "$19 / seat"
    ]
  ],
  "filename": "scrape_results.csv",
  "diff": {
    "added": 1,
    "removed": 0,
    "changed": 2
  }
}

GET

Check your credits

https://scrape.usesieve.com/api/me/credits

Shows the account’s plan and credit usage for the current calendar month. Runs consume credits based on the compute they use; the free plan includes 100 credits per month.

Request

curl --request GET \
  --url https://scrape.usesieve.com/api/me/credits \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Response 200

{
  "plan": "free",
  "limit": 100,
  "used": 20,
  "remaining": 80,
  "period": "2026-07"
}

API Reference

Start a scrape run

Request Body

Get run status & results

URL Parameters

Send a follow-up instruction

URL Parameters

Request Body

Create a monitor from a run

URL Parameters

Request Body

List your monitors

Trigger a monitor run

URL Parameters

Get run results

URL Parameters

Check your credits