> ## Documentation Index
> Fetch the complete documentation index at: https://developer.instantly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List conversions

> Lists the conversions recorded in a UTC date range, newest first, each with the last email before it, whether the person clicked, opened or only received it, and the event's properties. The person's email is included for API keys that can also read people.


Requires one of the following scopes: `email_marketing_conversions:read`, `email_marketing_conversions:all`, `all:read`, `all:all`



## OpenAPI

````yaml https://api.instantly.ai/openapi/api_v2.json get /api/v2/email-marketing/conversions
openapi: 3.1.0
info:
  title: API Explorer
  description: >-
    The entire API V2 documentation is interactive and can be tested here. To
    the right side of every endpoint you will see a box with an example request.
    You can click on the "Try it" button to send a request to the server right
    from the docs. You will need to provide an API key by clicking the
    `ApiKeyAuth_token` blue text.
  version: 2.0.0
servers:
  - url: https://api.instantly.ai
    description: Instantly API Server
security:
  - ApiKeyAuth: []
tags:
  - name: Analytics
    description: Endpoints related to analytics
    x-group: Analytics
  - name: OAuth
    description: >-
      OAuth authentication endpoints for connecting Google and Microsoft email
      accounts
    x-group: OAuth
  - name: Account
    description: An email account that can be used to send campaigns
    x-group: Account
  - name: Campaign
    description: A campaign that can be sent to a list of recipients
    x-group: Campaign
  - name: Email
    description: >-
      A campaign email, a reply, a manually sent email, or any other email
      that's visible in the Unibox
    x-group: Email
  - name: EmailVerification
    description: A single email verification
    x-group: Email Verification
  - name: LeadList
    description: A list used to store leads
    x-group: Lead List
  - name: InboxPlacementTest
    description: An inbox placement test
    x-group: Inbox Placement Test
  - name: InboxPlacementAnalytics
    description: Analytics data for individual emails in inbox placement tests
    x-group: Inbox Placement Analytics
  - name: InboxPlacementBlacklistAndSpamAssassinReport
    description: Report data for an inbox placement test
    x-group: Inbox Placement Blacklist And SpamAssassin Report
  - name: AIInboxManager
    description: An AI Inbox Manager agent
    x-group: AI Inbox Manager
  - name: AIDeliverabilityAgent
    description: An AI Deliverability Agent
    x-group: AI Deliverability Agent
  - name: AILeadFinderAgent
    description: An AI Lead Finder Agent
    x-group: AI Lead Finder Agent
  - name: LocalBusiness
    description: >-
      A local business found by the Local businesses search. Search businesses
      by category and location, then convert them into leads with a verified
      email in a lead list or a campaign.
    x-group: Local Business
  - name: Creator
    description: >-
      A social media creator found by the Creators search. Search creators by
      platform, niche, audience and location, then convert them into leads with
      their email.
    x-group: Creator
  - name: APIKey
    description: API Key
    x-group: API Key
  - name: AccountCampaignMapping
    description: Account Campaign Mapping
    x-group: Account Campaign Mapping
  - name: Lead
    description: A lead entity representing an individual lead
    x-group: Lead
  - name: BackgroundJob
    description: A background job that can be used to perform long-running tasks
    x-group: Background Job
  - name: CustomTag
    description: >-
      A custom tag for organizing and categorizing accounts and campaigns. You
      can use them as filters in apis that list accounts and campaigns.
    x-group: Custom Tag
  - name: CustomTagMapping
    description: >-
      This entity represents a tag being assigned to a specific campaign or
      email account. When an email account is assigned a tag, a new custom tag
      mapping entry is created, which connects the tag (`tag_id` field) with the
      email account (`resource_id` field). You can use it to see which tag si
      connected to which resource.
    x-group: Custom Tag Mapping
  - name: BlockListEntry
    description: A blocked email or domain
    x-group: Block List Entry
  - name: LeadLabel
    description: A custom label for categorizing and managing leads
    x-group: Lead Label
  - name: Workspace
    description: A workspace entity representing a workspace
    x-group: Workspace
  - name: SuperSearchEnrichment
    description: >-
      An enrichment can take different forms, such as email enrichment or
      LinkedIn enrichment. Leads may be imported from SuperSearch using the
      dedicated endpoint, or enriched directly within a list or campaign by
      attaching an enrichment to it.
    x-group: SuperSearch Enrichment
  - name: WorkspaceGroupMember
    description: >-
      A member of a workspace group. You can use the endpoints within this
      entity to manage the members of a workspace group.
    x-group: Workspace Group Member
  - name: WorkspaceMember
    description: A member of a workspace with associated user details
    x-group: Workspace Member
  - name: CampaignSubsequence
    description: A subsequence entity representing a follow-up sequence
    x-group: Campaign Subsequence
  - name: AuditLog
    description: Audit log records for tracking system activities
    x-group: Audit Log
  - name: AISalesAgent
    description: >-
      An AI Sales Development Representative that autonomously manages outreach
      campaigns
    x-group: AI Sales Agent
  - name: Webhook
    description: A webhook subscription for receiving event notifications
    x-group: Webhook
  - name: WebhookEvent
    description: A webhook event that was sent or attempted to be sent
    x-group: Webhook Event
  - name: DFYEmailAccountOrder
    description: A Done-For-You email account order
    x-group: DFY Email Account Order
  - name: DomainForwarding
    description: Web forwarding configuration for a domain ordered through Instantly
    x-group: Domain Forwarding
  - name: CustomPromptTemplate
    description: Custom prompt templates for creating custom prompts
    x-group: Custom Prompt Template
  - name: SalesFlow
    description: >-
      Manages how sales users view and interact with campaign and lead lists
      within the sales flow.
    x-group: Sales Flow
  - name: EmailTemplate
    description: A campaign email template
    x-group: Email Template
  - name: WorkspaceBilling
    description: Workspace Billing
    x-group: Workspace Billing
  - name: CRMActions
    description: CRM related actions
    x-group: CRM Actions
  - name: Conversion
    description: >-
      A conversion event received for a person, credited to the emails they got
      before it.
    x-group: Conversion
  - name: EngageItem
    description: >-
      A unified Engage item representing a campaign, AI agent, automation
      workflow, broadcast, or journey.
    x-group: Engage Item
paths:
  /api/v2/email-marketing/conversions:
    get:
      tags:
        - Conversion
      summary: List conversions
      description: >-
        Lists the conversions recorded in a UTC date range, newest first, each
        with the last email before it, whether the person clicked, opened or
        only received it, and the event's properties. The person's email is
        included for API keys that can also read people.



        Requires one of the following scopes:
        `email_marketing_conversions:read`, `email_marketing_conversions:all`,
        `all:read`, `all:all`
      operationId: listConversions
      parameters:
        - schema:
            type: string
            format: date
            example: '2026-08-01'
          example: '2026-08-01'
          in: query
          name: start_date
          required: true
          description: First UTC day of the period (YYYY-MM-DD)
        - schema:
            type: string
            format: date
            example: '2026-08-31'
          example: '2026-08-31'
          in: query
          name: end_date
          required: true
          description: >-
            Last UTC day of the period (YYYY-MM-DD); the period spans at most
            366 days, both ends included
        - schema:
            type: string
            enum:
              - instantly
              - api
              - calendly
              - typeform
              - shopify
              - woocommerce
              - wix
              - jotform
              - intercom
              - pipedrive
              - salesforce
              - hubspot
              - highlevel
              - leadconnector
              - zoho_crm
            example: api
          example: api
          in: query
          name: source
          required: false
          description: Producer of the conversion event
        - schema:
            type: string
            minLength: 2
            maxLength: 60
            pattern: ^[A-Za-z0-9._-]+$
            example: subscription_started
          example: subscription_started
          in: query
          name: event_name
          required: false
          description: Name of the conversion event
        - schema:
            type: string
            enum:
              - direct
              - influenced
              - received
              - none
            example: direct
          example: direct
          in: query
          name: attribution
          required: false
          description: Only conversions with this attribution
        - schema:
            type: string
            minLength: 1
            maxLength: 64
            example: journey-12ab
          example: journey-12ab
          in: query
          name: journey_id
          required: false
          description: Only conversions credited to this journey
        - schema:
            type: string
            minLength: 1
            maxLength: 64
            example: broadcast-42ef
          example: broadcast-42ef
          in: query
          name: broadcast_id
          required: false
          description: Only conversions credited to this broadcast
        - schema:
            type: string
            minLength: 1
            maxLength: 200
            example: starter
          example: starter
          in: query
          name: group_value
          required: false
          description: Only conversions with this group value
        - schema:
            type: integer
            minimum: 1
            maximum: 365
            example: 7
          example: 7
          in: query
          name: lookback_days
          required: false
          description: >-
            Credit each conversion again from the emails sent this many days
            before it; ignored when longer than the window it was recorded with
        - schema:
            type: boolean
            default: false
            example: true
          example: true
          in: query
          name: include_touches
          required: false
          description: Add every email sent in the window to each conversion
        - schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
            example: 50
          example: 50
          in: query
          name: limit
          required: false
          description: Page size
        - schema:
            type: string
            minLength: 1
            maxLength: 512
            example: 2026-08-20T10:00:00.000Z#0198c2a4
          example: 2026-08-20T10:00:00.000Z#0198c2a4
          in: query
          name: starting_after
          required: false
          description: The next_starting_after value of the previous page
      responses:
        '200':
          description: The list of Conversion
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    description: The list of Conversion
                    items:
                      $ref: '#/components/schemas/Conversion'
                  next_starting_after:
                    type:
                      - 'null'
                      - string
                    description: >-
                      The filter for getting the next items after this one, this
                      could either be a UUID, a timestamp, on an email depending
                      on the specific API
                additionalProperties: false
                required:
                  - items
        '400':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    example: 400
                  error:
                    type: string
                    example: Bad Request
                  message:
                    type: string
                    example: 'name: Invalid domain name format'
                  code:
                    type: string
                    example: VALIDATION_ERROR
        '401':
          description: >-
            This request is unauthorized (either the Authorization header is
            missing or invalid, or the API key has been revoked)
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                      - 401
                    examples:
                      - 401
                    example: 401
                  error:
                    type: string
                    enum:
                      - Unauthorized
                    examples:
                      - Unauthorized
                    example: Unauthorized
                  message:
                    type: string
                    examples:
                      - Missing Authorization header
                    example: Missing Authorization header
                required:
                  - statusCode
                  - error
                  - message
        '402':
          description: >-
            This request cannot be fulfilled because the workspace does not have
            an active paid plan
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                      - 402
                    examples:
                      - 402
                    example: 402
                  error:
                    type: string
                    enum:
                      - Payment Required
                    examples:
                      - Payment Required
                    example: Payment Required
                  message:
                    type: string
                    examples:
                      - Workspace does not have an active paid plan
                    example: Workspace does not have an active paid plan
                required:
                  - statusCode
                  - error
                  - message
        '404':
          description: The requested resource was not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                      - 404
                    examples:
                      - 404
                    example: 404
                  error:
                    type: string
                    enum:
                      - Not Found
                    examples:
                      - Not Found
                    example: Not Found
                  message:
                    type: string
                    examples:
                      - Resource not found
                    example: Resource not found
                required:
                  - statusCode
                  - error
                  - message
        '429':
          description: >-
            You have exceeded the rate limit. Please check the rate limit docs
            for more information.
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                      - 429
                    examples:
                      - 429
                    example: 429
                  error:
                    type: string
                    enum:
                      - Too Many Requests
                    examples:
                      - Too Many Requests
                    example: Too Many Requests
                  message:
                    type: string
                    examples:
                      - Rate limit exceeded
                    example: Rate limit exceeded
                required:
                  - statusCode
                  - error
                  - message
components:
  schemas:
    Conversion:
      title: Conversion
      description: >-
        A conversion event received for a person, credited to the emails they
        got before it.
      x-tags:
        - Schemas
        - Conversion
      type: object
      properties:
        conversion_id:
          type: string
          description: Receipt ID of the conversion event
          readOnly: true
          example: 0198c2a4-3f1e-7000-8000-000000000000
        person_id:
          type: string
          description: Person who converted
          readOnly: true
          example: 0198c2a4-3f1e-7000-8000-000000000001
        source:
          type: string
          description: Producer of the conversion event
          readOnly: true
          example: api
        event_name:
          type: string
          description: Name of the conversion event
          readOnly: true
          example: subscription_started
        occurred_at:
          type: string
          description: When the conversion happened
          readOnly: true
          format: date-time
          example: '2026-08-20T10:00:00.000Z'
        attribution:
          type: string
          description: >-
            direct: clicked an email before converting; influenced: opened one;
            received: only got emails; none: got no email in the lookback window
          readOnly: true
          enum:
            - direct
            - influenced
            - received
            - none
          example: direct
        last_touch:
          type: object
          description: >-
            The email clicked most recently, else the one opened most recently,
            else the one delivered most recently
          readOnly: true
          properties:
            origin:
              type: string
              enum:
                - journey
                - broadcast
              example: journey
            email_id:
              type: string
              description: ID of the sent email
              example: email-8f3a
            journey_id:
              type: string
              description: Journey that sent the email
              example: journey-12ab
            version:
              type: integer
              description: Journey version that sent the email
              example: 3
            step_id:
              type: string
              description: Journey step that sent the email
              example: step-1
            run_id:
              type: string
              description: Journey run that sent the email
              example: run-77cd
            broadcast_id:
              type: string
              description: Broadcast that sent the email
              example: broadcast-42ef
            sent_at:
              type: string
              format: date-time
              example: '2026-08-18T09:00:00.000Z'
            delivered_at:
              type: string
              format: date-time
              example: '2026-08-18T09:00:05.000Z'
            opened_at:
              type: string
              format: date-time
              description: First recorded open
              example: '2026-08-18T10:12:00.000Z'
            clicked_at:
              type: string
              format: date-time
              description: Latest click before the conversion, across links
              example: '2026-08-18T10:13:00.000Z'
          required:
            - origin
            - email_id
            - sent_at
        emails_in_window:
          type: integer
          description: Emails sent to the person within the lookback window
          readOnly: true
          example: 3
        lookback_days:
          type: integer
          description: >-
            Lookback window the conversion was classified with, or the shorter
            lookback_days asked for
          readOnly: true
          example: 30
        group_by_property:
          type:
            - 'null'
            - string
          description: Event property the group value was read from
          readOnly: true
          example: plan
        group_value:
          type:
            - 'null'
            - string
          description: Value of the group-by property on the event
          readOnly: true
          example: starter
        history_complete:
          type: boolean
          description: >-
            False when the person's email history was too long to read in full,
            so an earlier email may be missing
          readOnly: true
          example: true
        email:
          type:
            - 'null'
            - string
          description: >-
            Current email of the person; only for API keys that can also read
            people, and absent once the person is deleted
          readOnly: true
          example: ana@example.com
        days_since_last_touch:
          type:
            - 'null'
            - number
          description: >-
            Days from the last touch (its latest send, delivery, open or click)
            to the conversion
          readOnly: true
          example: 2.5
        properties:
          type:
            - 'null'
            - object
          description: >-
            Properties of the conversion event; text values are cut to 200
            characters
          readOnly: true
          additionalProperties:
            type:
              - string
              - number
              - boolean
          example:
            plan: starter
            seats: 3
        touches:
          type:
            - 'null'
            - array
          description: >-
            Every email sent to the person in the lookback window, newest first,
            at most 50; only with include_touches
          readOnly: true
          items:
            type: object
            properties:
              origin:
                type: string
                enum:
                  - journey
                  - broadcast
                examples:
                  - journey
                example: journey
              email_id:
                type: string
                description: ID of the sent email
                examples:
                  - email-8f3a
                example: email-8f3a
              journey_id:
                type: string
                description: Journey that sent the email
                examples:
                  - journey-12ab
                example: journey-12ab
              version:
                type: integer
                description: Journey version that sent the email
                examples:
                  - 3
                example: 3
              step_id:
                type: string
                description: Journey step that sent the email
                examples:
                  - step-1
                example: step-1
              run_id:
                type: string
                description: Journey run that sent the email
                examples:
                  - run-77cd
                example: run-77cd
              broadcast_id:
                type: string
                description: Broadcast that sent the email
                examples:
                  - broadcast-42ef
                example: broadcast-42ef
              sent_at:
                type: string
                format: date-time
                examples:
                  - '2026-08-18T09:00:00.000Z'
                example: '2026-08-18T09:00:00.000Z'
              delivered_at:
                type: string
                format: date-time
                examples:
                  - '2026-08-18T09:00:05.000Z'
                example: '2026-08-18T09:00:05.000Z'
              opened_at:
                type: string
                format: date-time
                description: First recorded open
                examples:
                  - '2026-08-18T10:12:00.000Z'
                example: '2026-08-18T10:12:00.000Z'
              clicked_at:
                type: string
                format: date-time
                description: Latest click before the conversion, across links
                examples:
                  - '2026-08-18T10:13:00.000Z'
                example: '2026-08-18T10:13:00.000Z'
            required:
              - origin
              - email_id
              - sent_at
        touches_truncated:
          type:
            - 'null'
            - boolean
          description: >-
            True when more than 50 emails were sent in the window, so the oldest
            are missing from touches
          readOnly: true
          example: true
      required:
        - conversion_id
        - person_id
        - source
        - event_name
        - occurred_at
        - attribution
        - emails_in_window
        - lookback_days
        - history_complete
      additionalProperties: false
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.