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.

GET /stats/query_ambassadors

Try it

cURL

cURL

curl --request GET \
  --url https://api.growi.io/api/public/v1/stats/query_ambassadors \
  --header 'Authorization: Bearer <token>'

200

{
  "data": [
    {
      "campaign_affiliate_id": 456,
      "user_id": 789,
      "email": "[e-mail]",
      "first_name": "John",
      "last_name": "Doe",
      "creator_name": "John Doe",
      "revenue": 5000.5,
      "commission": 500.05,
      "orders_count": 45,
      "clicks": 1500,
      "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"
  }
}

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

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

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

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

{
  "data": [
    {
      "campaign_affiliate_id": 456,
      "user_id": 789,
      "email": "[e-mail]",
      "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:

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:

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=[e-mail]" \
     -H "Authorization: Bearer YOUR_PUBLIC_API_KEY"

Email Filter (Multiple - Comma Separated)

Filter by multiple ambassador emails using comma-separated values:

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=[e-mail],[e-mail],[e-mail]" \
     -H "Authorization: Bearer YOUR_PUBLIC_API_KEY"

First Name Filter

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

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):

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:

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

# 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

{
  "error": "Missing required parameter(s): start_date, end_date, campaign_id"
}

401 Unauthorized - Invalid API Key

{
  "error": "Not Authenticated"
}

429 Too Many Requests - Rate Limit Exceeded

{
  "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

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: "[e-mail]" }
);

// With multiple emails
const multiFiltered = await getAmbassadorStats(
  "growi-sk-YOUR_API_KEY",
  123,
  "09/01/2025",
  "09/30/2025",
  { email: "[e-mail],[e-mail]", 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

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='[e-mail],[e-mail]',
    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

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: '[e-mail],[e-mail]',
  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=[e-mail],[e-mail],[e-mail]

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.

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

start_date · string<date> · default: 09/01/2025 · required

Start date in MM/DD/YYYY format

end_date · string<date> · default: 09/30/2025 · required

End date in MM/DD/YYYY format

campaign_id · integer · required

ID of the campaign to query

page · integer · default: 1

Page number for pagination. Default is 1.

per_page · integer · default: 20

Number of results per page. Default is 20. Maximum is 100.

Required range: x <= 100

search · string

Search across email, first name, last name, or full name

email · string<email>

Filter by ambassador email(s). Supports comma-separated values

first_name · string

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

last_name · string

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

status · enum<string> · default: all

Filter by tracking event status

Available options: all, paid, pending, canceled, due

Response

200

application/json

Ambassador stats retrieved successfully

data · object[]

Show child attributes

data. campaign_affiliate_id · integer

Unique identifier for the campaign affiliate relationship

Example:

456

data. user_id · integer

Unique identifier for the user/ambassador

Example:

789

data. email · string

Ambassador's email address

Example:

"[e-mail]"

data. first_name · string

Ambassador's first name

Example:

"John"

data. last_name · string

Ambassador's last name

Example:

"Doe"

data. creator_name · string

Full name of the ambassador (first + last)

Example:

"John Doe"

data. revenue · number

Total revenue generated in dollars (for the specified date range)

Example:

5000.5

data. commission · number

Total commission earned in dollars

Example:

500.05

data. orders_count · integer

Total number of completed orders

Example:

45

data. clicks · integer

Total number of link clicks (page views)

Example:

1500

data. joined_campaign_date · string

Date the ambassador joined the campaign (MM/DD/YYYY format)

Example:

"01/15/2024"

meta · object

Show child attributes

meta. total_ambassadors · integer

Total number of ambassadors matching the query (across all pages)

Example:

150

meta. current_page · integer

Current page number

Example:

1

meta. per_page · integer

Number of results per page

Example:

20

meta. total_pages · integer

Total number of pages available

Example:

8

meta. start_date · string

Query start date

Example:

"09/01/2025"

meta. end_date · string

Query end date

Example:

"09/30/2025"

meta. campaign_id · string

Campaign ID queried

Example:

"123"