---
title: "Get Referrals Report V2"
method: POST
path: "/v2/reports/referrals"
tags: ["Reports", "Human Referrals"]
---

# Get Referrals Report V2

`POST /v2/reports/referrals`

Get referral traffic report from the hourly aggregated materialized view (UTC-based).

Supports date_interval="hour", calendar intervals through "year", "quarter", and "relative_week".

## Request body

- ReferralsQueryV2
  - `date_interval` 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year' | 'relative_week' — Date interval for the report. (only used with date dimension)
  - `dimensions` string[] — Dimensions to group the report by.
  - `metrics` string[], required
  - `order_by` object — Custom ordering of the report results. The order is a record of key-value pairs where: - key is the field to order by, which can be a metric or dimension - value is the direction of the order, either 'asc' for ascending or 'desc' for descending. When not specified, the default order is the first metric in the query descending.
  - `pagination` Pagination — Offset-based pagination parameters.
    - `limit` integer — Maximum number of results to return. Default is 10,000, maximum is 50,000.
    - `offset` integer — Offset for the results. Used for pagination.
  - `domain` string, required — Domain to query logs for.
  - `start_date` string, date-time, required — 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` string, date-time — End date in UTC. Accepts same formats as start_date. Defaults to now UTC if omitted.
  - `organization_id` string, uuid, nullable
  - `metric_filters` NumericMetricFilter[] — Numeric filters applied after report metrics are calculated.
    - `field` string, required
    - `operator` '>' | '>=' | '<' | '<=' | '=' | '==' | '!=', required
    - `value` union, required
      - integer
      - number
  - `filters` union[] — Filters for referrals report.
    - union
      - PathFilter — Filter by request path
        - `field` 'path', required
        - `operator` 'is' | 'not_is' | 'in' | 'not_in' | 'contains' | 'not_contains' | 'matches' | 'contains_case_insensitive' | 'not_contains_case_insensitive', required
        - `value` union, required
          - string
          - string[]
      - ReferralSourceFilter — Filter by referral source
        - `field` 'referral_source', required
        - `operator` 'is' | 'not_is' | 'in' | 'not_in' | 'contains' | 'not_contains' | 'matches' | 'contains_case_insensitive' | 'not_contains_case_insensitive', required
        - `value` union, required
          - 'openai' | 'none' | 'anthropic' | 'deepseek' | 'perplexity' | 'you' | 'grok' | 'microsoft' | 'gemini' | 'internal' | 'other'
          - string[]
      - ReferralTypeFilter — Filter by referral type
        - `field` 'referral_type', required
        - `operator` 'is' | 'not_is' | 'in' | 'not_in' | 'contains' | 'not_contains' | 'matches' | 'contains_case_insensitive' | 'not_contains_case_insensitive', required
        - `value` union, required
          - 'internal' | 'referer' | 'utm' | 'none'
          - string[]

## Response `200`

Successful Response

- Response — Base response model for reports.
  - `info` Info, required — Base model for report information.
    - `total_rows` integer, required
    - `query` object, nullable
  - `data` Result[], required
    - `metrics` union[], required
      - union
        - integer
        - number
    - `dimensions` union[], required
      - union
        - string
        - string, uuid

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/cooper-square-technologies/apis/external-api.md) · [All operations](https://skmtc.net/cooper-square-technologies/apis/external-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/cooper-square-technologies/external-api/versions/ab03b3c80494/schema)