# Find leads

Filter your pipeline by stage, or search it by company, segment or city.

`GET /v1/leads` takes filters as query parameters. Combine them freely; every filter applies to every page.

| Parameter | Example | Finds |
| --- | --- | --- |
| `stage` | `proposal` | Leads at that stage: `prospect`, `contacted`, `meeting`, `proposal`, `won` or `lost`. |
| `q` | `dental` | Leads whose company name, segment or city matches. |

<CodeGroup>

```bash title="cURL"
curl -G "https://api.leadup.group/v1/leads" \
  -d stage=proposal \
  -d q=campinas \
  -H "Authorization: Bearer $LEADUP_API_KEY"
```

```ts title="Node.js"
const url = new URL("https://api.leadup.group/v1/leads")

url.searchParams.set("stage", "proposal")
url.searchParams.set("q", "campinas")

const page = await (await fetch(url, { headers: { Authorization: `Bearer ${process.env.LEADUP_API_KEY}` } })).json()
```

</CodeGroup>

The key needs `leads:read`. Results come a page at a time; see [pagination](/guides/pagination).