# Retrieve funnel data

> Retrieves funnel data to track user progression through specific stages of a conversion process.
>
> Rate limit: 2 requests per second.

## OpenAPI

```yaml
/api-specs/export-analytics-api.yaml post /api/v1/client-api/metrics/funnel/
openapi: 3.1.0
info:
  title: Adapty Export Analytics API
  version: 1.0.0
  description: |
    The Adapty Export Analytics API allows you to export your analytics data to CSV or JSON format, 
    giving you the flexibility to dive deeper into your app's performance metrics, customize reports, 
    and analyze trends over time. With this API, you can easily pull detailed analytics data, 
    making it convenient to track, share, and refine your data insights as needed.
servers:
  - url: https://api-admin.adapty.io
    description: Production server
security:
  - apikeyAuth: []
paths:
  /api/v1/client-api/metrics/funnel/:
    post:
      summary: Retrieve funnel data
      description: |-
        Retrieves funnel data to track user progression through specific stages of a conversion process.

        Rate limit: 2 requests per second.
      operationId: retrieveFunnelData
      security:
        - apikeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FunnelDataRequest"
            examples:
              basic:
                summary: Basic funnel data request
                value:
                  filters:
                    date:
                      - "2024-01-01"
                      - "2024-12-31"
                    compare_date:
                      - "2023-01-01"
                      - "2023-12-31"
                    offer_category:
                      - promotional
                  period_unit: quarter
                  show_value_as: absolute
                  format: csv
      responses:
        "200":
          description: Funnel data retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FunnelDataResponse"
              example:
                data:
                  - title: Total
                    type: total
                    values:
                      - period: -2
                        title: Install
                        value: 2
                        value_relative: 100
                        relative_changes: 0
                        following_changes:
                          title: Drop off
                          value: 2
                          value_relative: 100
                        churn_reason_title: ""
                        churn_reasons: []
                        values: []
                      - period: -1
                        title: Paywall displayed
                        value: 0
                        value_relative: 0
                        relative_changes: 0
                        following_changes:
                          title: Drop off
                          value: 0
                          value_relative: 0
                        churn_reason_title: ""
                        churn_reasons: []
                        values: []
            text/csv:
              schema:
                type: string
                description: Funnel data in CSV format
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedError"
        "429":
          description: Rate limit exceeded. Maximum 2 requests per second per API key.
components:
  schemas:
    FunnelDataRequest:
      type: object
      required:
        - filters
      properties:
        filters:
          $ref: "#/components/schemas/MetricsFilters"
        period_unit:
          type: string
          enum:
            - day
            - week
            - month
            - quarter
            - year
          description: Specify the time interval for aggregating analytics data
        show_value_as:
          type: string
          enum:
            - absolute
            - relative
            - both
          description: Specify how values are displayed
        segmentation:
          type: string
          description: Sets the basis for segmentation
        format:
          type: string
          enum:
            - json
            - csv
          description: Specify the export file format
          default: json
    FunnelDataResponse:
      type: object
      description: Response containing funnel analysis data showing user progression through conversion stages
      properties:
        data:
          type: array
          description: Array of funnel segments showing different stages of the conversion process
          items:
            $ref: "#/components/schemas/FunnelSegment"
    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              source:
                type: string
              errors:
                type: array
                items:
                  type: string
        error_code:
          type: string
        status_code:
          type: integer
    UnauthorizedError:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              source:
                type: string
              errors:
                type: array
                items:
                  type: string
        error_code:
          type: string
        status_code:
          type: integer
    MetricsFilters:
      type: object
      required:
        - date
      properties:
        date:
          type: array
          items:
            type: string
          description: Enter the date or time period for which you want to retrieve chart data
        compare_date:
          type: array
          items:
            type: string
          description: Enter the comparison date or time period
        store:
          type: array
          items:
            type: string
          description: Filter by the app store where the purchase was made
        country:
          type: array
          items:
            type: string
          description: Filter by the 2-letter country code where the purchase took place
        store_product_id:
          type: array
          items:
            type: string
          description: Unique identifier of a product from the app store
        duration:
          type: array
          items:
            type: string
          description: Specify the subscription duration
        attribution_source:
          type: array
          items:
            type: string
          description: The source integration for attribution
        attribution_status:
          type: array
          items:
            type: string
          description: Indicates if the attribution is organic or non-organic
        attribution_channel:
          type: array
          items:
            type: string
          description: Marketing channel that led to the transaction
        attribution_campaign:
          type: array
          items:
            type: string
          description: Marketing campaign that brought the transaction
        attribution_adgroup:
          type: array
          items:
            type: string
          description: Attribution ad group that brought the transaction
        attribution_adset:
          type: array
          items:
            type: string
          description: Attribution ad set that led to the transaction
        attribution_creative:
          type: array
          items:
            type: string
          description: Specific visual or text elements in an ad or campaign tracked to measure effectiveness
        offer_category:
          type: array
          items:
            type: string
          description: Specify the offer categories you want to retrieve data for
        offer_type:
          type: array
          items:
            type: string
          description: Specify the offer types you want to retrieve data for
        offer_id:
          type: array
          items:
            type: string
          description: Specify the specific offers you want to retrieve data for
    FunnelSegment:
      type: object
      description: A funnel segment representing a stage in the conversion process
      properties:
        title:
          type: string
          description: Display title for this funnel segment
        type:
          type: string
          description: Type of funnel segment ('total' for aggregated data)
        values:
          type: array
          description: Array of funnel values showing progression through stages
          items:
            $ref: "#/components/schemas/FunnelValue"
    FunnelValue:
      type: object
      description: Individual funnel stage value showing user progression and drop-off
      properties:
        period:
          type: integer
          description: Period number in the funnel (-2 = Install, -1 = Paywall displayed, etc.)
        title:
          type: string
          description: Display title for this funnel stage
        value:
          type: integer
          description: Number of users who reached this stage
        value_relative:
          type: number
          description: Percentage of users who reached this stage relative to the first stage
        relative_changes:
          type: number
          description: Change in conversion rate compared to previous period
        following_changes:
          type: object
          description: Information about users who dropped off after this stage
          properties:
            title:
              type: string
              description: Title for the drop-off stage
            value:
              type: integer
              description: Number of users who dropped off
            value_relative:
              type: number
              description: Percentage of users who dropped off
        churn_reason_title:
          type: string
          description: Title describing the reason for churn at this stage
        churn_reasons:
          type: array
          description: Array of specific churn reasons
          items:
            type: object
        values:
          type: array
          description: Additional nested values for this funnel stage
          items:
            type: object
  securitySchemes:
    apikeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: |
        You need to authenticate your API requests with your secret API key as an Authorization header. 
        You can find it in the App Settings. The format is `Api-Key {YOUR_SECRET_API_KEY}`, 
        for example: `Api-Key secret_live_...`.
```