---
title: "Get Leads"
method: GET
path: "/api/leads"
tags: ["Leads"]
---

# Get Leads

`GET /api/leads`

Retrieve a paginated list of leads with optional filtering, sorting, and field selection.

## Query parameters

- `limit` integer
- `page` integer
- `sort` string
- `search` string
- `fields` string
- `status` string
- `externalId` string
- `source` 'inbound' | 'gtm' | 'api' | 'manual' | 'wordpress' | 'import'
- `labelId` string
- `website` string
- `utm_source` string
- `utm_medium` string
- `utm_campaign` string
- `updated_after` string, date-time

## Response `200`

Paginated list of leads

- object
  - `success` boolean
  - `data` Lead[]
    - `id` string — Unique lead identifier
    - `externalId` string, nullable — Customer-owned lead identifier, unique within the organization
    - `name` string — Lead name
    - `email` string, email — Lead email
    - `phone` string — Lead phone number
    - `status` 'open' | 'qualified' | 'won' | 'lost' — Lead status
    - `value` number — Lead value
    - `note` string — Notes about the lead
    - `custom` string — Custom data. Accepts a string or JSON object/array. Non-string values are automatically stringified. Always returned as a string in responses.
    - `lossReason` string, nullable — Reason for loss
    - `conversionName` string — Conversion source name
    - `source` 'inbound' | 'gtm' | 'api' | 'manual' | 'wordpress' | 'import' — Lead source
    - `website` string — Website URL
    - `path` string — Page path where lead was captured
    - `referrer` string, nullable — Referring URL
    - `country` string, nullable — Detected country code
    - `gclid` string — Google Ads Click ID
    - `dclid` string — Google Display Click ID
    - `wbraid` string — Google Ads web-to-app click ID
    - `gbraid` string — Google Ads app-to-web click ID
    - `ga4cid` string — Google Analytics 4 Client ID
    - `ga4sid` string — Google Analytics 4 Session ID
    - `fbc` string — Meta (Facebook) Click ID
    - `fbp` string — Meta (Facebook) Browser ID
    - `msclkid` string — Microsoft Ads Click ID
    - `ttclid` string — TikTok Click ID
    - `twclid` string — X (Twitter) Click ID
    - `rdt_cid` string — Reddit Click ID
    - `sccid` string — Snapchat Click ID
    - `epik` string — Pinterest click ID
    - `li_fat_id` string — LinkedIn Click ID
    - `utm_source` string — UTM source
    - `utm_medium` string — UTM medium
    - `utm_campaign` string — UTM campaign
    - `utm_content` string — UTM content
    - `utm_term` string — UTM term
    - `ad_storage` boolean — Ad storage consent
    - `ad_user_data` boolean — Ad user data consent
    - `analytics_storage` boolean — Analytics storage consent
    - `ad_personalization` boolean — Ad personalization consent
    - `googleAdsCampaignId` string — Google Ads Campaign ID
    - `googleAdsCustomerId` string — Google Ads Customer ID
    - `googleAdsClickDate` string, date — Google Ads click date
    - `googleAdsCampaignName` string — Google Ads Campaign Name
    - `googleAdsAdGroupId` string — Google Ads Ad Group ID
    - `googleAdsAdGroupName` string — Google Ads Ad Group Name
    - `googleAdsAdId` string — Google Ads Ad ID
    - `googleAdsDevice` string — Google Ads device
    - `googleAdsAdNetworkType` string — Google Ads network type
    - `googleAdsClickType` string — Google Ads click type
    - `googleAdsSlot` string — Google Ads slot
    - `labelId` string — Label ID
    - `selectedConversionEventId` string — Selected conversion event ID
    - `createdAt` string, date-time — Creation timestamp
    - `updatedAt` string, date-time — Last update timestamp
    - `qualifiedAt` string, date-time, nullable — Qualification timestamp
    - `expiresAt` string, date-time — Expiration timestamp
  - `meta` PaginatedMeta
    - `pagination` object
      - `limit` integer
      - `page` integer
      - `totalPages` integer
      - `total` integer
      - `hasMore` boolean
    - `requestId` string
    - `timestamp` string, date-time

## Other responses

- `400` — Invalid filter or date parameter
- `401` — Missing or invalid API key
- `500` — Server error

---

[API](https://skmtc.net/octanist/apis/octanist-api.md) · [All operations](https://skmtc.net/octanist/apis/octanist-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/octanist/octanist-api/revisions/a0620637a051/schema)