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

# Get Ambassador Stats

> Retrieves aggregated statistics for campaign ambassadors, grouped by individual affiliate. This endpoint provides performance metrics including revenue, commission, order counts, and clicks for ambassadors within a specified date range.

Retrieves aggregated statistics for campaign ambassadors, grouped by individual affiliate. This endpoint provides performance metrics including revenue, commission, order counts, refund amounts, and clicks for ambassadors within a specified date range.

## Request Parameters

| Parameter        | Type    | Description                                                       | Required |
| ---------------- | ------- | ----------------------------------------------------------------- | -------- |
| `start_date`     | String  | Start date in MM/DD/YYYY format                                   | Yes      |
| `end_date`       | String  | End date in MM/DD/YYYY format                                     | Yes      |
| `campaign_id`    | Integer | ID of the campaign to query                                       | Yes      |
| `page`           | Integer | Page number for pagination. Default is 1.                         | No       |
| `per_page`       | Integer | Number of results per page. Default is 20. Maximum is 100.        | No       |
| `include_clicks` | String  | Set to `true` to include click data. Default is `false`.          | No       |
| `search`         | String  | Search across email, first name, last name, or full name          | No       |
| `email`          | String  | Filter by ambassador email(s). Supports comma-separated values    | No       |
| `first_name`     | String  | Filter by ambassador first name (case-insensitive, partial match) | No       |
| `last_name`      | String  | Filter by ambassador last name (case-insensitive, partial match)  | No       |

## Request Examples

### Basic Request

```bash theme={null}
curl -X GET "https://api.growi.io/api/public/v1/stats/query_ambassadors?start_date=09/01/2025&end_date=09/30/2025&campaign_id=123&page=1&per_page=20" \
     -H "Authorization: Bearer YOUR_PUBLIC_API_KEY" \
     -H "Content-Type: application/json"
```

### With Clicks

```bash theme={null}
curl -X GET "https://api.growi.io/api/public/v1/stats/query_ambassadors?start_date=09/01/2025&end_date=09/30/2025&campaign_id=123&include_clicks=true" \
     -H "Authorization: Bearer YOUR_PUBLIC_API_KEY" \
     -H "Content-Type: application/json"
```

### With Clicks

```bash theme={null}
curl -X GET "https://api.growi.io/api/public/v1/stats/query_ambassadors?start_date=09/01/2025&end_date=09/30/2025&campaign_id=123&include_clicks=true" \
     -H "Authorization: Bearer YOUR_PUBLIC_API_KEY"
```

## Response Example

```json theme={null}
{
  "data": [
    {
      "campaign_affiliate_id": 456,
      "user_id": 789,
      "email": "ambassador@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "creator_name": "John Doe",
      "revenue": 5000.5,
      "commission": 500.05,
      "orders_count": 45,
      "clicks": 1500,
      "refund_amount": 150.25,
      "joined_campaign_date": "01/15/2024"
    }
  ],
  "meta": {
    "total_ambassadors": 150,
    "current_page": 1,
    "per_page": 20,
    "total_pages": 8,
    "start_date": "09/01/2025",
    "end_date": "09/30/2025",
    "campaign_id": "123"
  }
}
```

## Response Fields

| Field                          | Type    | Description                                                                   |
| ------------------------------ | ------- | ----------------------------------------------------------------------------- |
| `data`                         | Array   | Array of ambassador statistics objects                                        |
| `data[].campaign_affiliate_id` | Integer | Unique identifier for the campaign affiliate relationship                     |
| `data[].user_id`               | Integer | Unique identifier for the user/ambassador                                     |
| `data[].email`                 | String  | Ambassador's email address                                                    |
| `data[].first_name`            | String  | Ambassador's first name                                                       |
| `data[].last_name`             | String  | Ambassador's last name                                                        |
| `data[].creator_name`          | String  | Full name of the ambassador (first + last)                                    |
| `data[].revenue`               | Number  | Total revenue generated in dollars (for the specified date range)             |
| `data[].commission`            | Number  | Total commission earned in dollars                                            |
| `data[].orders_count`          | Integer | Total number of completed orders                                              |
| `data[].clicks`                | Integer | Total number of unique link clicks. Default is 0 unless `include_clicks=true` |
| `data[].refund_amount`         | Number  | Total refunded/canceled order amount in dollars                               |
| `data[].joined_campaign_date`  | String  | Date the ambassador joined the campaign (MM/DD/YYYY format)                   |
| `meta`                         | Object  | Pagination and query metadata                                                 |
| `meta.total_ambassadors`       | Integer | Total number of ambassadors matching the query (across all pages)             |
| `meta.current_page`            | Integer | Current page number                                                           |
| `meta.per_page`                | Integer | Number of results per page                                                    |
| `meta.total_pages`             | Integer | Total number of pages available                                               |
| `meta.start_date`              | String  | Query start date                                                              |
| `meta.end_date`                | String  | Query end date                                                                |
| `meta.campaign_id`             | String  | Campaign ID queried                                                           |

## Filter Examples

### Search Filter

The `search` parameter searches across email, first name, last name, and full name:

```bash theme={null}
curl -X GET "https://api.growi.io/api/public/v1/stats/query_ambassadors?start_date=09/01/2025&end_date=09/30/2025&campaign_id=123&search=john" \
     -H "Authorization: Bearer YOUR_PUBLIC_API_KEY"
```

### Email Filter (Single)

Filter by a specific ambassador email:

```bash theme={null}
curl -X GET "https://api.growi.io/api/public/v1/stats/query_ambassadors?start_date=09/01/2025&end_date=09/30/2025&campaign_id=123&email=john@example.com" \
     -H "Authorization: Bearer YOUR_PUBLIC_API_KEY"
```

### Email Filter (Multiple - Comma Separated)

Filter by multiple ambassador emails using comma-separated values:

```bash theme={null}
curl -X GET "https://api.growi.io/api/public/v1/stats/query_ambassadors?start_date=09/01/2025&end_date=09/30/2025&campaign_id=123&email=john@example.com,jane@example.com,bob@example.com" \
     -H "Authorization: Bearer YOUR_PUBLIC_API_KEY"
```

### First Name Filter

Filter by ambassador first name (case-insensitive, partial match):

```bash theme={null}
curl -X GET "https://api.growi.io/api/public/v1/stats/query_ambassadors?start_date=09/01/2025&end_date=09/30/2025&campaign_id=123&first_name=John" \
     -H "Authorization: Bearer YOUR_PUBLIC_API_KEY"
```

### Last Name Filter

Filter by ambassador last name (case-insensitive, partial match):

```bash theme={null}
curl -X GET "https://api.growi.io/api/public/v1/stats/query_ambassadors?start_date=09/01/2025&end_date=09/30/2025&campaign_id=123&last_name=Smith" \
     -H "Authorization: Bearer YOUR_PUBLIC_API_KEY"
```

### Combined Filters

You can combine multiple filters:

```bash theme={null}
curl -X GET "https://api.growi.io/api/public/v1/stats/query_ambassadors?start_date=09/01/2025&end_date=09/30/2025&campaign_id=123&first_name=John&last_name=Doe&include_clicks=true" \
     -H "Authorization: Bearer YOUR_PUBLIC_API_KEY"
```

### Pagination

```bash theme={null}
# Get first page (20 results by default)
curl -X GET "https://api.growi.io/api/public/v1/stats/query_ambassadors?start_date=09/01/2025&end_date=09/30/2025&campaign_id=123&page=1" \
     -H "Authorization: Bearer YOUR_PUBLIC_API_KEY"

# Get second page
curl -X GET "https://api.growi.io/api/public/v1/stats/query_ambassadors?start_date=09/01/2025&end_date=09/30/2025&campaign_id=123&page=2" \
     -H "Authorization: Bearer YOUR_PUBLIC_API_KEY"

# Get 50 results per page
curl -X GET "https://api.growi.io/api/public/v1/stats/query_ambassadors?start_date=09/01/2025&end_date=09/30/2025&campaign_id=123&per_page=50" \
     -H "Authorization: Bearer YOUR_PUBLIC_API_KEY"
```

## Important Notes

### Time Periods

All metrics (revenue, commission, orders, clicks, refunds) are filtered by the specified date range. The `start_date` and `end_date` parameters filter tracking events by their `occurred_at` timestamp (when the sale or click happened), not by when the ambassador joined the campaign.

To analyze different time periods, make separate API calls with different date ranges:

* **This Month**: `start_date=12/01/2024&end_date=12/31/2024`
* **Last Month**: `start_date=11/01/2024&end_date=11/30/2024`
* **Year to Date**: `start_date=01/01/2024&end_date=12/31/2024`
* **Custom Range**: Any range you specify

### Pagination

* **Default**: 20 results per page
* **Maximum**: 100 results per page
* **Performance**: Always use pagination for campaigns with many ambassadors
* **All ambassadors shown**: Even ambassadors with 0 sales appear in results if they match filters
* Use `total_pages` in the meta response to iterate through all pages

## Error Responses

### 400 Bad Request - Missing Required Parameters

```json theme={null}
{
  "error": "Missing required parameter(s): start_date, end_date, campaign_id"
}
```

### 401 Unauthorized - Invalid API Key

```json theme={null}
{
  "error": "Not Authenticated"
}
```

### 429 Too Many Requests - Rate Limit Exceeded

```json theme={null}
{
  "error": "Rate limit exceeded. Please wait 2 seconds between requests.",
  "retry_after": 2
}
```

## Rate Limiting

This endpoint is subject to the standard Public API rate limits:

* **Frequency Limit**: 2-second minimum interval between requests
* **Hourly Limit**: 40 requests per hour (default, configurable per organization)

## Performance Tips

To ensure fast response times:

1. **Use Pagination**: Always paginate for campaigns with many ambassadors
2. **Apply Filters**: Use email/name filters to narrow results
3. **Clicks**: Only add `include_clicks=true` when you specifically need click data

## Integration Examples

### JavaScript/Node.js

```javascript theme={null}
const axios = require("axios");

async function getAmbassadorStats(
  apiKey,
  campaignId,
  startDate,
  endDate,
  filters = {}
) {
  try {
    const params = {
      campaign_id: campaignId,
      start_date: startDate,
      end_date: endDate,
      ...filters,
    };

    const response = await axios.get(
      "https://api.growi.io/api/public/v1/stats/query_ambassadors",
      {
        headers: { Authorization: `Bearer ${apiKey}` },
        params,
      }
    );

    return response.data;
  } catch (error) {
    console.error("Error:", error.response?.data || error.message);
    throw error;
  }
}

// Usage examples

// Fast - without clicks
const stats = await getAmbassadorStats(
  "growi-sk-YOUR_API_KEY",
  123,
  "09/01/2025",
  "09/30/2025"
);

// With clicks (requires index for good performance)
const statsWithClicks = await getAmbassadorStats(
  "growi-sk-YOUR_API_KEY",
  123,
  "09/01/2025",
  "09/30/2025",
  { include_clicks: "true" }
);

// With email filter
const filtered = await getAmbassadorStats(
  "growi-sk-YOUR_API_KEY",
  123,
  "09/01/2025",
  "09/30/2025",
  { email: "john@example.com" }
);

// With multiple emails
const multiFiltered = await getAmbassadorStats(
  "growi-sk-YOUR_API_KEY",
  123,
  "09/01/2025",
  "09/30/2025",
  { email: "john@example.com,jane@example.com", include_clicks: "true" }
);

console.log(`Total Ambassadors: ${stats.meta.total_ambassadors}`);
stats.data.forEach((ambassador) => {
  console.log(
    `${ambassador.creator_name}: $${ambassador.revenue} revenue, ${ambassador.orders_count} orders, ${ambassador.clicks} clicks, $${ambassador.refund_amount} refunded`
  );
});
```

### Python

```python theme={null}
import requests

def get_ambassador_stats(api_key, campaign_id, start_date, end_date, **filters):
    url = 'https://api.growi.io/api/public/v1/stats/query_ambassadors'
    headers = {'Authorization': f'Bearer {api_key}'}
    params = {
        'campaign_id': campaign_id,
        'start_date': start_date,
        'end_date': end_date,
        **filters
    }

    response = requests.get(url, headers=headers, params=params)
    response.raise_for_status()
    return response.json()

# Usage examples

# Fast - without clicks
stats = get_ambassador_stats(
    'growi-sk-YOUR_API_KEY',
    123,
    '09/01/2025',
    '09/30/2025'
)

# With clicks
stats_with_clicks = get_ambassador_stats(
    'growi-sk-YOUR_API_KEY',
    123,
    '09/01/2025',
    '09/30/2025',
    include_clicks='true'
)

# With filters
filtered_stats = get_ambassador_stats(
    'growi-sk-YOUR_API_KEY',
    123,
    '09/01/2025',
    '09/30/2025',
    email='john@example.com,jane@example.com',
    first_name='John',
    include_clicks='true'
)

print(f"Total Ambassadors: {stats['meta']['total_ambassadors']}")
for ambassador in stats['data']:
    print(f"{ambassador['creator_name']}: ${ambassador['revenue']} revenue, "
          f"{ambassador['orders_count']} orders, {ambassador['clicks']} clicks, "
          f"${ambassador['refund_amount']} refunded")
```

### Ruby

```ruby theme={null}
require 'net/http'
require 'json'
require 'cgi'

def get_ambassador_stats(api_key, campaign_id, start_date, end_date, filters = {})
  uri = URI('https://api.growi.io/api/public/v1/stats/query_ambassadors')
  params = {
    campaign_id: campaign_id,
    start_date: start_date,
    end_date: end_date
  }.merge(filters)

  uri.query = URI.encode_www_form(params)

  request = Net::HTTP::Get.new(uri)
  request['Authorization'] = "Bearer #{api_key}"

  response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
    http.request(request)
  end

  JSON.parse(response.body)
end

# Usage examples

# Fast - without clicks
stats = get_ambassador_stats(
  'growi-sk-YOUR_API_KEY',
  123,
  '09/01/2025',
  '09/30/2025'
)

# With clicks
stats_with_clicks = get_ambassador_stats(
  'growi-sk-YOUR_API_KEY',
  123,
  '09/01/2025',
  '09/30/2025',
  include_clicks: 'true'
)

# With multiple emails
filtered = get_ambassador_stats(
  'growi-sk-YOUR_API_KEY',
  123,
  '09/01/2025',
  '09/30/2025',
  email: 'john@example.com,jane@example.com',
  include_clicks: 'true'
)

puts "Total Ambassadors: #{stats['meta']['total_ambassadors']}"
stats['data'].each do |ambassador|
  puts "#{ambassador['creator_name']}: $#{ambassador['revenue']} revenue, " \
       "#{ambassador['orders_count']} orders, #{ambassador['clicks']} clicks, " \
       "$#{ambassador['refund_amount']} refunded"
end
```

## Filtering Best Practices

### Multiple Emails

When filtering by multiple emails, use comma-separated values without spaces (or with spaces - both work):

```
?email=user1@example.com,user2@example.com,user3@example.com
```

The system will:

* Split on commas
* Trim whitespace
* Convert to lowercase for case-insensitive matching

### Search vs Specific Filters

* Use **`search`** for broad queries across all name/email fields
* Use **`email`**, **`first_name`**, or **`last_name`** for precise filtering

### Including Clicks

By default, clicks are not included to ensure fast response times. To include click data:

```
?include_clicks=true
```

**Note:** Including clicks may increase response time. For optimal performance, combine with specific email filters to limit the number of ambassadors queried.


## OpenAPI

````yaml GET /stats/query_ambassadors
openapi: 3.0.1
info:
  title: Growi API
  description: >-
    API documentation for Growi platform, showcasing the public tracking event
    endpoint
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.growi.io/api/public/v1
security:
  - bearerAuth: []
paths:
  /stats/query_ambassadors:
    get:
      description: >-
        Retrieves aggregated statistics for campaign ambassadors, grouped by
        individual affiliate. This endpoint provides performance metrics
        including revenue, commission, order counts, and clicks for ambassadors
        within a specified date range.
      parameters:
        - name: start_date
          in: query
          required: true
          example: 09/01/2025
          schema:
            type: string
            format: date
            default: 09/01/2025
          description: Start date in MM/DD/YYYY format
        - name: end_date
          in: query
          required: true
          example: 09/30/2025
          schema:
            type: string
            format: date
            default: 09/30/2025
          description: End date in MM/DD/YYYY format
        - name: campaign_id
          in: query
          required: true
          example: 123
          schema:
            type: integer
          description: ID of the campaign to query
        - name: page
          in: query
          required: false
          example: 1
          schema:
            type: integer
            default: 1
          description: Page number for pagination. Default is 1.
        - name: per_page
          in: query
          required: false
          example: 20
          schema:
            type: integer
            default: 20
            maximum: 100
          description: Number of results per page. Default is 20. Maximum is 100.
        - name: search
          in: query
          required: false
          example: john
          schema:
            type: string
          description: Search across email, first name, last name, or full name
        - name: email
          in: query
          required: false
          example: ambassador@example.com
          schema:
            type: string
            format: email
          description: Filter by ambassador email(s). Supports comma-separated values
        - name: first_name
          in: query
          required: false
          example: John
          schema:
            type: string
          description: Filter by ambassador first name (case-insensitive, partial match)
        - name: last_name
          in: query
          required: false
          example: Doe
          schema:
            type: string
          description: Filter by ambassador last name (case-insensitive, partial match)
        - name: status
          in: query
          required: false
          example: all
          schema:
            type: string
            enum:
              - all
              - paid
              - pending
              - canceled
              - due
            default: all
          description: Filter by tracking event status
      responses:
        '200':
          description: Ambassador stats retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        campaign_affiliate_id:
                          type: integer
                          example: 456
                          description: >-
                            Unique identifier for the campaign affiliate
                            relationship
                        user_id:
                          type: integer
                          example: 789
                          description: Unique identifier for the user/ambassador
                        email:
                          type: string
                          example: ambassador@example.com
                          description: Ambassador's email address
                        first_name:
                          type: string
                          example: John
                          description: Ambassador's first name
                        last_name:
                          type: string
                          example: Doe
                          description: Ambassador's last name
                        creator_name:
                          type: string
                          example: John Doe
                          description: Full name of the ambassador (first + last)
                        revenue:
                          type: number
                          example: 5000.5
                          description: >-
                            Total revenue generated in dollars (for the
                            specified date range)
                        commission:
                          type: number
                          example: 500.05
                          description: Total commission earned in dollars
                        orders_count:
                          type: integer
                          example: 45
                          description: Total number of completed orders
                        clicks:
                          type: integer
                          example: 1500
                          description: Total number of link clicks (page views)
                        joined_campaign_date:
                          type: string
                          example: 01/15/2024
                          description: >-
                            Date the ambassador joined the campaign (MM/DD/YYYY
                            format)
                  meta:
                    type: object
                    properties:
                      total_ambassadors:
                        type: integer
                        example: 150
                        description: >-
                          Total number of ambassadors matching the query (across
                          all pages)
                      current_page:
                        type: integer
                        example: 1
                        description: Current page number
                      per_page:
                        type: integer
                        example: 20
                        description: Number of results per page
                      total_pages:
                        type: integer
                        example: 8
                        description: Total number of pages available
                      start_date:
                        type: string
                        example: 09/01/2025
                        description: Query start date
                      end_date:
                        type: string
                        example: 09/30/2025
                        description: Query end date
                      campaign_id:
                        type: string
                        example: '123'
                        description: Campaign ID queried
        '400':
          description: Bad Request - Missing required parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too Many Requests - Rate limit exceeded
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: >-
                      Rate limit exceeded. Please wait 2 seconds between
                      requests.
                  retry_after:
                    type: integer
                    example: 2
components:
  schemas:
    Error:
      required:
        - error
        - message
      type: object
      properties:
        error:
          type: string
        message:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````