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

# Promoter reports

> <Note>With this endpoint you can get the report data grouped by promoters. Data is updated once a day, at midnight. This endpoint supports pagination, similar to other endpoints, by passing `page` param.<br/><br/>If you want to iterate through all promoters, you **must start with** `page=1` and continue to next pages based on header pagination links from the response. The paginated promoters are always ordered by the total revenue made (not the revenue brought during the selected period).<br/><br/>If **page param is omitted**, we'll return **top 50 promoters** by **revenue amount** on the selected period. You can get the **top 50 promoters** sorted by a different metric using the `top_50` parameter.</Note><Tip> **HTTP Request** <br/> `GET https://firstpromoter.com/api/v1/reports/promoters`</Tip>



## OpenAPI

````yaml openapi-reports GET /promoters
openapi: 3.0.1
info:
  title: FirstPromoter Reports API
  description: >-
    The Reports API allows you to retrieve aggregated data of your affiliate
    performance across 18 data points.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://firstpromoter.com/api/v1/reports
security:
  - apiKeyAuth: []
paths:
  /promoters:
    get:
      description: >-
        <Note>With this endpoint you can get the report data grouped by
        promoters. Data is updated once a day, at midnight. This endpoint
        supports pagination, similar to other endpoints, by passing `page`
        param.<br/><br/>If you want to iterate through all promoters, you **must
        start with** `page=1` and continue to next pages based on header
        pagination links from the response. The paginated promoters are always
        ordered by the total revenue made (not the revenue brought during the
        selected period).<br/><br/>If **page param is omitted**, we'll return
        **top 50 promoters** by **revenue amount** on the selected period. You
        can get the **top 50 promoters** sorted by a different metric using the
        `top_50` parameter.</Note><Tip> **HTTP Request** <br/> `GET
        https://firstpromoter.com/api/v1/reports/promoters`</Tip>
      parameters:
        - name: selected_fields[]
          in: query
          description: >-
            An array of fields to return on the response. By default selected
            fields are `revenue_amount`, `clicks_count`, `referrals_count`,
            `customers_count`
          schema:
            type: array
            items:
              type: string
              enum:
                - revenue_amount
                - clicks_count
                - referrals_count
                - customers_count
                - active_customers
                - monthly_churn
                - net_revenue_amount
                - sales_count
                - refunds_count
                - cancelled_customers_count
                - promoter_earnings_amount
                - non_link_customers
                - referrals_to_customers_cr
                - 3m_epc
                - 6m_epc
                - clicks_to_customers_cr
                - clicks_to_referrals_cr
                - promoter_paid_amount
          style: form
          explode: true
          allowReserved: true
        - name: promoter_ids[]
          in: query
          description: >-
            An array of ids of the selected Promoters. If omitted, all Promoters
            will be returned
          schema:
            type: array
            items:
              type: string
        - name: group_by
          in: query
          description: >-
            Period to group by. By default is `month`. For day grouping,
            reporting period span is limited at `90 days`
          schema:
            type: string
            enum:
              - day
              - month
              - year
        - name: top_50
          in: query
          description: >-
            Show the top 50 promoters by selected metric. By default is
            `revenue_amount` but it can be any value passed on
            `selected_fields[]`.
          schema:
            type: string
            enum:
              - revenue_amount
              - clicks_count
              - referrals_count
              - customers_count
              - active_customers
              - monthly_churn
              - net_revenue_amount
              - sales_count
              - refunds_count
              - cancelled_customers_count
              - promoter_earnings_amount
              - non_link_customers
              - referrals_to_customers_cr
              - 3m_epc
              - 6m_epc
              - clicks_to_customers_cr
              - clicks_to_referrals_cr
              - promoter_paid_amount
        - name: start_date
          in: query
          description: Beginning of reporting period. Default is set as `12 months ago`
          schema:
            type: string
        - name: end_date
          in: query
          description: End of reporting period. Default is set as `today`
          schema:
            type: string
      responses:
        '200':
          description: Promoter report response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PromoterReport'
        '401':
          description: Authentication Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntity'
components:
  schemas:
    PromoterReport:
      type: object
      properties:
        promoter_name:
          description: Promoter's name
          type: string
          example: Test Promoter
        promoter_id:
          description: ID of the promoter
          type: number
          example: 5487437
        items:
          type: array
          items:
            $ref: '#/components/schemas/Report'
        revenue_amount:
          type: string
          example: $613.17
        clicks_count:
          type: number
          example: 100
        referrals_count:
          type: number
          example: 60
        customers_count:
          type: number
          example: 30
    AuthenticationError:
      type: string
      example: Bad credentials
    UnprocessableEntity:
      type: object
      properties:
        message:
          type: string
          example: Selected Fields invalid !
        code:
          type: string
          example: invalid_params
    Report:
      type: object
      properties:
        revenue_amount:
          type: string
          example: $613.17
        clicks_count:
          type: number
          example: 100
        referrals_count:
          type: number
          example: 60
        customers_count:
          type: number
          example: 30
        period:
          type: string
          example: Sep 2024
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY

````