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

# Get Leads

`GET /api/leads`

## Request

- Base URL: `https://octanist.com`
- URL: `https://octanist.com/api/leads`
- Auth: API key in header `X-API-KEY`

Retrieve a paginated list of leads with optional filtering, sorting, and field selection. Each lead includes the converting pixel `session`, scoped journey `sessions`, and flattened attribution fields for backward compatibility.

## 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
    - `session` PixelSession, nullable: Public converting pixel session, or null when the lead has no linked pixel session. Omits organizationId, ip, userAgent, and octaCid.
      - `id` string: Pixel session ID
      - `source` string: Session source
      - `visitorId` string, nullable: Visitor ID
      - `startedAt` string, date-time, nullable: Session start timestamp
      - `lastActivityAt` string, date-time, nullable: Last activity timestamp
      - `consentAnalytics` boolean, nullable: Analytics consent
      - `consentMarketing` boolean, nullable: Marketing consent
      - `consentSource` string, nullable: Consent source
      - `gclid` string, nullable: Google Ads Click ID
      - `gclsrc` string, nullable: Google Ads click source
      - `gclidCapturedAt` string, date-time, nullable: When gclid was captured
      - `gclidSource` string, nullable: How gclid was captured
      - `dclid` string, nullable: Google Display Click ID
      - `wbraid` string, nullable: Google Ads web-to-app click ID
      - `gbraid` string, nullable: Google Ads app-to-web click ID
      - `fbc` string, nullable: Meta (Facebook) Click ID
      - `fbp` string, nullable: Meta (Facebook) Browser ID
      - `msclkid` string, nullable: Microsoft Ads Click ID
      - `ttclid` string, nullable: TikTok Click ID
      - `li_fat_id` string, nullable: LinkedIn Click ID
      - `twclid` string, nullable: X (Twitter) Click ID
      - `sccid` string, nullable: Snapchat Click ID
      - `epik` string, nullable: Pinterest click ID
      - `rdt_cid` string, nullable: Reddit Click ID
      - `ga4cid` string, nullable: Google Analytics 4 Client ID
      - `ga4sid` string, nullable: Google Analytics 4 Session ID
      - `utm_source` string, nullable: UTM source
      - `utm_medium` string, nullable: UTM medium
      - `utm_campaign` string, nullable: UTM campaign
      - `utm_content` string, nullable: UTM content
      - `utm_term` string, nullable: UTM term
      - `googleAdsCustomerId` string, nullable: Google Ads Customer ID
      - `googleAdsClickDate` string, date, nullable: Google Ads click date
      - `googleAdsCampaignId` string, nullable: Google Ads Campaign ID
      - `googleAdsCampaignName` string, nullable: Google Ads Campaign Name
      - `googleAdsAdGroupId` string, nullable: Google Ads Ad Group ID
      - `googleAdsAdGroupName` string, nullable: Google Ads Ad Group Name
      - `googleAdsAdId` string, nullable: Google Ads Ad ID
      - `googleAdsDevice` string, nullable: Google Ads device
      - `googleAdsAdNetworkType` string, nullable: Google Ads network type
      - `googleAdsClickType` string, nullable: Google Ads click type
      - `googleAdsSlot` string, nullable: Google Ads slot
      - `referrer` string, nullable: Referring URL
      - `domain` string, nullable: Website domain
      - `path` string, nullable: Page path
      - `country` string, nullable: Detected country code
      - `deviceType` string, nullable: Device type
    - `sessions` PixelSession[]: Scoped journey sessions for this lead. Same shape as session.
      - `id` string: Pixel session ID
      - `source` string: Session source
      - `visitorId` string, nullable: Visitor ID
      - `startedAt` string, date-time, nullable: Session start timestamp
      - `lastActivityAt` string, date-time, nullable: Last activity timestamp
      - `consentAnalytics` boolean, nullable: Analytics consent
      - `consentMarketing` boolean, nullable: Marketing consent
      - `consentSource` string, nullable: Consent source
      - `gclid` string, nullable: Google Ads Click ID
      - `gclsrc` string, nullable: Google Ads click source
      - `gclidCapturedAt` string, date-time, nullable: When gclid was captured
      - `gclidSource` string, nullable: How gclid was captured
      - `dclid` string, nullable: Google Display Click ID
      - `wbraid` string, nullable: Google Ads web-to-app click ID
      - `gbraid` string, nullable: Google Ads app-to-web click ID
      - `fbc` string, nullable: Meta (Facebook) Click ID
      - `fbp` string, nullable: Meta (Facebook) Browser ID
      - `msclkid` string, nullable: Microsoft Ads Click ID
      - `ttclid` string, nullable: TikTok Click ID
      - `li_fat_id` string, nullable: LinkedIn Click ID
      - `twclid` string, nullable: X (Twitter) Click ID
      - `sccid` string, nullable: Snapchat Click ID
      - `epik` string, nullable: Pinterest click ID
      - `rdt_cid` string, nullable: Reddit Click ID
      - `ga4cid` string, nullable: Google Analytics 4 Client ID
      - `ga4sid` string, nullable: Google Analytics 4 Session ID
      - `utm_source` string, nullable: UTM source
      - `utm_medium` string, nullable: UTM medium
      - `utm_campaign` string, nullable: UTM campaign
      - `utm_content` string, nullable: UTM content
      - `utm_term` string, nullable: UTM term
      - `googleAdsCustomerId` string, nullable: Google Ads Customer ID
      - `googleAdsClickDate` string, date, nullable: Google Ads click date
      - `googleAdsCampaignId` string, nullable: Google Ads Campaign ID
      - `googleAdsCampaignName` string, nullable: Google Ads Campaign Name
      - `googleAdsAdGroupId` string, nullable: Google Ads Ad Group ID
      - `googleAdsAdGroupName` string, nullable: Google Ads Ad Group Name
      - `googleAdsAdId` string, nullable: Google Ads Ad ID
      - `googleAdsDevice` string, nullable: Google Ads device
      - `googleAdsAdNetworkType` string, nullable: Google Ads network type
      - `googleAdsClickType` string, nullable: Google Ads click type
      - `googleAdsSlot` string, nullable: Google Ads slot
      - `referrer` string, nullable: Referring URL
      - `domain` string, nullable: Website domain
      - `path` string, nullable: Page path
      - `country` string, nullable: Detected country code
      - `deviceType` string, nullable: Device type
  - `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

## Changes

- **2026-08-31** `29a41aff4975`: 2 info
  - added the optional property `data/items/session` to the response with the `200` status
  - added the optional property `data/items/sessions` to the response with the `200` status

[Operation history](https://skmtc.dev/octanist/apis/octanist-api/changes/api/leads/get.md)

---

[API](https://skmtc.dev/octanist/apis/octanist-api.md) - [All operations](https://skmtc.dev/octanist/apis/octanist-api/llms.txt) - [OpenAPI document](https://skmtc.dev/octanist/apis/octanist-api/revisions/29a41aff4975?raw)
