# Start a task
Give the agent a job in plain language. Set a hard lead-credit cap. Reuse the idempotency key only for the same request.
**Request:** `POST https://leadsagent.io/api/v1/tasks`
**Access:** leads:write.
**Response:** HTTP 202. data is a task object. Save data.id and poll status_url.

## Parameters

- `prompt` (string): Required. 3–4,000 characters.
- `max_leads` (integer): 1–5,000 credits; default 100. This is the hard task cap, including follow-ups.
- `idempotency_key` (string): Optional. 8–128 characters. Reuse only for the same prompt and budget.
- `allow_questions` (boolean): Optional. Default true; false asks the agent to make reasonable assumptions.

## Request body

```json
{
  "prompt": "Find 20 dentists in Austin with emails",
  "max_leads": 20,
  "idempotency_key": "austin-dentists-001",
  "allow_questions": true
}
```

## cURL

```sh
curl --fail-with-body --silent --show-error --request POST "$LEADSAGENT_API_BASE/tasks" -H "X-API-Key: $LEADSAGENT_API_KEY" -H "Content-Type: application/json" --data '{
  "prompt": "Find 20 dentists in Austin with emails",
  "max_leads": 20,
  "idempotency_key": "austin-dentists-001",
  "allow_questions": true
}'
```

## Example response

```
{
  "request_id": "6c4d0c26-8aa3-44b0-a50a-51b832b29465",
  "status": "success",
  "data": {
    "id": "73bd1ccb-1a44-4b41-84da-4ea7a5ad03f4",
    "kind": "agent",
    "status": "queued",
    "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": 0,
    "results_ready": false,
    "status_url": "/api/v1/tasks/73bd1ccb-1a44-4b41-84da-4ea7a5ad03f4"
  },
  "meta": {}
}
```

## Notes

- A repeated key returns the original task. A changed request should use a new key.
- The task runs in the background; HTTP 202 means accepted, not completed.

[Open the full API reference](https://leadsagent.io/documentation/api-reference)