openapi: 3.2.0
info:
  title: External Human Referrals API
  version: 6551bd49db665ffb7f80780b3e150b8e8b780cc3
servers:
- url: https://api.tryprofound.com
  description: Production Server
tags:
- name: Human Referrals
paths:
  /v1/reports/referrals:
    post:
      tags:
      - Human Referrals
      summary: Get Referrals Report V1
      description: 'Get referral traffic report from the daily aggregated materialized view.


        This endpoint queries pre-aggregated daily referral data, making it efficient

        for large date ranges and high-traffic sites.'
      operationId: get_referrals_report_v1_v1_reports_referrals_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReferralsQuery'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
      - BearerAuth: []
  /v2/reports/referrals:
    post:
      tags:
      - Human Referrals
      summary: Get Referrals Report V2
      description: 'Get referral traffic report from the hourly aggregated materialized view (UTC-based).


        Supports date_interval="hour", calendar intervals through "year", "quarter", and "relative_week".'
      operationId: get_referrals_report_v2_v2_reports_referrals_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReferralsQueryV2'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
      - BearerAuth: []
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ReferralTypeFilter:
      properties:
        field:
          type: string
          const: referral_type
          title: Field
        operator:
          type: string
          enum:
          - is
          - not_is
          - in
          - not_in
          - contains
          - not_contains
          - matches
          - contains_case_insensitive
          - not_contains_case_insensitive
          title: Operator
        value:
          anyOf:
          - type: string
            enum:
            - internal
            - referer
            - utm
            - none
          - items:
              type: string
              enum:
              - internal
              - referer
              - utm
              - none
            type: array
          title: Value
      type: object
      required:
      - field
      - operator
      - value
      title: ReferralTypeFilter
      description: Filter by referral type
    NumericMetricFilter:
      properties:
        field:
          type: string
          title: Field
        operator:
          type: string
          enum:
          - '>'
          - '>='
          - <
          - <=
          - '='
          - ==
          - '!='
          title: Operator
        value:
          anyOf:
          - type: integer
          - type: number
          title: Value
      type: object
      required:
      - field
      - operator
      - value
      title: NumericMetricFilter
    ReferralsQueryV2:
      properties:
        date_interval:
          type: string
          enum:
          - hour
          - day
          - week
          - month
          - quarter
          - year
          - relative_week
          title: Date Interval
          description: Date interval for the report. (only used with date dimension)
          default: day
        dimensions:
          items:
            type: string
            enum:
            - date
            - hour
            - host
            - path
            - referral_source
            - referral_type
          type: array
          title: Dimensions
          description: Dimensions to group the report by.
          default: []
        metrics:
          items:
            type: string
            enum:
            - visits
            - last_visit
          type: array
          title: Metrics
        order_by:
          additionalProperties:
            type: string
            enum:
            - asc
            - desc
          propertyNames:
            enum:
            - date
            - hour
            - host
            - path
            - referral_source
            - visits
            - last_visit
            - referral_type
          type: object
          title: Order By
          description: "\nCustom ordering of the report results.\n\nThe order is a record of key-value pairs where:\n- key is the field to order by, which can be a metric or dimension\n- value is the direction of the order, either 'asc' for ascending or 'desc' for descending.\n\nWhen not specified, the default order is the first metric in the query descending.\n        "
          default: {}
          examples:
          - date: asc
        pagination:
          $ref: '#/components/schemas/Pagination'
          description: Pagination settings for the report results.
        domain:
          type: string
          title: Domain
          description: Domain to query logs for.
        start_date:
          type: string
          format: date-time
          title: Start Date
          description: 'Start date for logs. Accepts: YYYY-MM-DD, YYYY-MM-DD HH:MM, YYYY-MM-DD HH:MM:SS, or full ISO timestamp.'
        end_date:
          type: string
          format: date-time
          title: End Date
          description: End date in UTC. Accepts same formats as start_date. Defaults to now UTC if omitted.
        organization_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Organization Id
        timezone:
          type: string
          title: Timezone
          description: IANA timezone name for date bucketing and filter boundaries.
          default: UTC
        metric_filters:
          items:
            $ref: '#/components/schemas/NumericMetricFilter'
          type: array
          title: Metric Filters
          description: Numeric filters applied after report metrics are calculated.
        filters:
          items:
            oneOf:
            - $ref: '#/components/schemas/PathFilter'
            - $ref: '#/components/schemas/ReferralSourceFilter'
            - $ref: '#/components/schemas/ReferralTypeFilter'
            discriminator:
              propertyName: field
              mapping:
                path: '#/components/schemas/PathFilter'
                referral_source: '#/components/schemas/ReferralSourceFilter'
                referral_type: '#/components/schemas/ReferralTypeFilter'
          type: array
          title: Filters
          description: Filters for referrals report.
      type: object
      required:
      - metrics
      - domain
      - start_date
      title: ReferralsQueryV2
    PathFilter:
      properties:
        field:
          type: string
          const: path
          title: Field
        operator:
          type: string
          enum:
          - is
          - not_is
          - in
          - not_in
          - contains
          - not_contains
          - matches
          - contains_case_insensitive
          - not_contains_case_insensitive
          title: Operator
        value:
          anyOf:
          - type: string
          - items:
              type: string
            type: array
          title: Value
      type: object
      required:
      - field
      - operator
      - value
      title: PathFilter
      description: Filter by request path
    ReferralSourceFilter:
      properties:
        field:
          type: string
          const: referral_source
          title: Field
        operator:
          type: string
          enum:
          - is
          - not_is
          - in
          - not_in
          - contains
          - not_contains
          - matches
          - contains_case_insensitive
          - not_contains_case_insensitive
          title: Operator
        value:
          anyOf:
          - type: string
          - items:
              type: string
            type: array
          title: Value
      type: object
      required:
      - field
      - operator
      - value
      title: ReferralSourceFilter
      description: 'Filter by referral source. Values are not enum-constrained so the platform''s shared

        provider filter can pass through IDs that have bot data but no referral data.'
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    Response:
      properties:
        info:
          $ref: '#/components/schemas/Info'
        data:
          items:
            $ref: '#/components/schemas/Result'
          type: array
          title: Data
      type: object
      required:
      - info
      - data
      title: Response
      description: Base response model for reports.
    Info:
      properties:
        total_rows:
          type: integer
          title: Total Rows
        query:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Query
      type: object
      required:
      - total_rows
      title: Info
      description: Base model for report information.
    ReferralsQuery:
      properties:
        date_interval:
          type: string
          enum:
          - hour
          - day
          - week
          - month
          - year
          - relative_week
          title: Date Interval
          description: Date interval for the report. (only used with date dimension)
          default: day
        dimensions:
          items:
            type: string
            enum:
            - date
            - host
            - path
            - referral_source
          type: array
          title: Dimensions
          description: Dimensions to group the report by.
          default: []
        metrics:
          items:
            type: string
            enum:
            - visits
            - last_visit
          type: array
          title: Metrics
        order_by:
          additionalProperties:
            type: string
            enum:
            - asc
            - desc
          propertyNames:
            enum:
            - date
            - host
            - path
            - referral_source
            - visits
            - last_visit
          type: object
          title: Order By
          description: "\nCustom ordering of the report results.\n\nThe order is a record of key-value pairs where:\n- key is the field to order by, which can be a metric or dimension\n- value is the direction of the order, either 'asc' for ascending or 'desc' for descending.\n\nWhen not specified, the default order is the first metric in the query descending.\n        "
          default: {}
          examples:
          - date: asc
        pagination:
          $ref: '#/components/schemas/Pagination'
          description: Pagination settings for the report results.
        domain:
          type: string
          title: Domain
          description: Domain to query logs for.
        start_date:
          type: string
          format: date-time
          title: Start Date
          description: 'Start date for logs. Accepts: YYYY-MM-DD, YYYY-MM-DD HH:MM, YYYY-MM-DD HH:MM:SS, or full ISO timestamp.'
        end_date:
          type: string
          format: date-time
          title: End Date
          description: End date for logs. Accepts same formats as start_date. Defaults to now if omitted.
        organization_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Organization Id
        metric_filters:
          items:
            $ref: '#/components/schemas/NumericMetricFilter'
          type: array
          title: Metric Filters
          description: Numeric filters applied after report metrics are calculated.
        filters:
          items:
            oneOf:
            - $ref: '#/components/schemas/PathFilter'
            - $ref: '#/components/schemas/ReferralSourceFilter'
            discriminator:
              propertyName: field
              mapping:
                path: '#/components/schemas/PathFilter'
                referral_source: '#/components/schemas/ReferralSourceFilter'
          type: array
          title: Filters
          description: Filters for referrals report.
      type: object
      required:
      - metrics
      - domain
      - start_date
      title: ReferralsQuery
    Pagination:
      properties:
        limit:
          type: integer
          maximum: 50000.0
          exclusiveMinimum: 0.0
          title: Limit
          description: Maximum number of results to return. Default is 10,000, maximum is 50,000.
          default: 10000
        offset:
          type: integer
          minimum: 0.0
          title: Offset
          description: Offset for the results. Used for pagination.
          default: 0
      type: object
      title: Pagination
      description: Offset-based pagination parameters.
    Result:
      properties:
        metrics:
          items:
            anyOf:
            - type: integer
            - type: number
            - type: string
          type: array
          title: Metrics
        dimensions:
          items:
            anyOf:
            - type: string
            - type: string
              format: uuid
          type: array
          title: Dimensions
      type: object
      required:
      - metrics
      - dimensions
      title: Result
      description: Base model for report results.
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
    BearerAuth:
      type: http
      scheme: bearer