GET · leads:read

Get a task

Read task status, progress, steps, questions, the agent reply, lead counts and result links.

Set up with your AI assistant

Paste the prompt into your coding assistant. It includes setup steps and a read-only connection check.

Request

Endpoint

GET https://leadsagent.io/api/v1/tasks/{id}

Set LEADSAGENT_API_KEY in your local environment. Send it in the X-API-Key header.

Bash · API base URL

export LEADSAGENT_API_BASE="https://leadsagent.io/api/v1"
# For a local backend:
# export LEADSAGENT_API_BASE="http://127.0.0.1:8001/api/v1"

Bash · curl

curl --fail-with-body --silent --show-error --request GET "$LEADSAGENT_API_BASE/tasks/$TASK_ID" -H "X-API-Key: $LEADSAGENT_API_KEY"

Replace TASK_ID with data.id from a task response. In PowerShell, use curl.exe and $env:LEADSAGENT_API_KEY. Save JSON in a file and pass --data-binary @request.json.

id (UUID): Required. The task ID returned by start-task or find-leads.

Response

data is a task object. Poll status_url every 10–20 seconds or wait for poll_after_seconds.

Example response

{
  "request_id": "6c4d0c26-8aa3-44b0-a50a-51b832b29465",
  "status": "success",
  "data": {
    "id": "73bd1ccb-1a44-4b41-84da-4ea7a5ad03f4",
    "kind": "agent",
    "status": "completed",
    "prompt": "Find 20 dentists in Austin with emails",
    "source": "API key · research-example",
    "max_leads": 20,
    "created_at": "2026-10-21T12:00:00+00:00",
    "updated_at": "2026-10-21T12:00:00+00:00",
    "steps": [],
    "lead_count": 20,
    "results_ready": true,
    "status_url": "/api/v1/tasks/73bd1ccb-1a44-4b41-84da-4ea7a5ad03f4",
    "poll_after_seconds": null,
    "links": {
      "view_url": "https://leadsagent.io/leads/view/artifact-id?sessionId=SESSION_ID&version=1",
      "download_url": "https://leadsagent.io/api/v1/downloads/{signed-token}",
      "download_expires_at": "2026-10-21T13:00:00Z"
    }
  },
  "meta": {}
}

Errors and retries explains status codes and retry rules. A successful request does not mean a background task has finished.

Read as Markdown