Partner stats endpoint

Tokenized access to partner event performance metrics

The partner stats endpoint provides secure, tokenized access to event performance analytics for partner activations. This allows event hosts and partners to view their event’s engagement metrics.

GET /api/partner-stats/[activationId]

Retrieves performance statistics for a specific partner activation using a secure access token.

Path parameters

activationId · string · required

Unique partner activation identifier

Query parameters

token · string · required

Secure access token for the activation

Tokens are generated when a partner activation is created and provide read-only access to stats.

format · string

Response format: omit for JSON, or set to csv for CSV export

Response (JSON format)

success · boolean · required

Indicates if the request was successful

data · object

Partner statistics data (returned on success)

Show data properties

activationId · string

Partner activation identifier

eventKey · string

Associated event identifier

eventName · string

Event name

tier · string

Partner tier level

range · object

Date range for the statistics

startAt · string

ISO 8601 start timestamp

endAt · string

ISO 8601 end timestamp

metrics · object

Performance metrics

clickCount · number

Total event detail views

outboundClickCount · number

Total clicks to external event links

calendarSyncCount · number

Total calendar additions

uniqueSessionCount · number

Unique visitor sessions (all actions)

uniqueViewSessionCount · number

Unique visitor sessions that viewed the event

uniqueOutboundSessionCount · number

Unique visitor sessions that clicked outbound links

uniqueCalendarSessionCount · number

Unique visitor sessions that synced to calendar

outboundSessionRate · number

Percentage of viewing sessions that clicked outbound (0-100)

calendarSessionRate · number

Percentage of viewing sessions that synced to calendar (0-100)

outboundInteractionRate · number

Percentage of total sessions that clicked outbound (0-100)

calendarInteractionRate · number

Percentage of total sessions that synced to calendar (0-100)

error · string

Error message (returned on failure)

Response (CSV format)

When format=csv, returns a CSV file with the following headers:

activation_id,event_key,event_name,tier,start_at,end_at,views,outbound_clicks,calendar_syncs,unique_sessions,unique_view_sessions,unique_outbound_sessions,unique_calendar_sessions,outbound_session_rate,calendar_session_rate,outbound_interaction_rate,calendar_interaction_rate

The response includes:

• Content-Type: text/csv; charset=utf-8
• Content-Disposition: attachment; filename="oooc-partner-stats-{eventKey}.csv"

Error codes

• 400 Bad Request: Missing token parameter
• 403 Forbidden: Invalid or expired token
• 404 Not Found: Activation ID not found
• 409 Conflict: Activation exists but is in an invalid state

Security

Tokens provide read-only access to partner statistics. They should be treated as sensitive credentials:

• Tokens are generated per-activation and cannot be regenerated
• Each token grants access only to its associated activation’s stats
• Tokens do not expire but can be invalidated if the activation is deleted
• Share tokens only with authorized partners or event hosts

Examples

JSON format

const activationId = 'act_abc123xyz';
const token = 'tok_secure_token_here';

const response = await fetch(
  `/api/partner-stats/${activationId}?token=${token}`
);

const result = await response.json();
// {
//   "success": true,
//   "data": {
//     "activationId": "act_abc123xyz",
//     "eventKey": "jazz-sunset-2026-03-15",
//     "eventName": "Jazz Night at Le Sunset",
//     "tier": "premium",
//     "range": {
//       "startAt": "2026-03-01T00:00:00.000Z",
//       "endAt": "2026-03-31T23:59:59.999Z"
//     },
//     "metrics": {
//       "clickCount": 1250,
//       "outboundClickCount": 342,
//       "calendarSyncCount": 158,
//       "uniqueSessionCount": 892,
//       "uniqueViewSessionCount": 867,
//       "uniqueOutboundSessionCount": 298,
//       "uniqueCalendarSessionCount": 142,
//       "outboundSessionRate": 34.4,
//       "calendarSessionRate": 16.4,
//       "outboundInteractionRate": 33.4,
//       "calendarInteractionRate": 15.9
//     }
//   }
// }

---

Use cases

Show Partner dashboards

Integrate the partner stats endpoint into custom dashboards:

// Fetch and display stats in a partner portal
async function loadPartnerStats(activationId, token) {
  const response = await fetch(
    `/api/partner-stats/${activationId}?token=${token}`
  );
  
  if (!response.ok) {
    throw new Error('Failed to load stats');
  }
  
  const { data } = await response.json();
  return data.metrics;
}

const metrics = await loadPartnerStats('act_xyz', 'tok_secret');
console.log(`Total views: ${metrics.clickCount}`);
console.log(`Conversion rate: ${metrics.outboundSessionRate}%`);

Show Automated reporting

Download CSV exports for regular reporting:

// Download stats as CSV for email reporting
async function exportStatsCSV(activationId, token) {
  const response = await fetch(
    `/api/partner-stats/${activationId}?token=${token}&format=csv`
  );
  
  const blob = await response.blob();
  const url = window.URL.createObjectURL(blob);
  const a = document.createElement('a');
  a.href = url;
  a.download = `partner-stats-${new Date().toISOString().split('T')[0]}.csv`;
  a.click();
}

exportStatsCSV('act_xyz', 'tok_secret');

Show Email notifications

Send periodic stats updates to partners:

// Server-side: Fetch and email stats weekly
async function sendWeeklyReport(activationId, token, recipientEmail) {
  const response = await fetch(
    `https://fete-finder.example.com/api/partner-stats/${activationId}?token=${token}`
  );
  
  const { data } = await response.json();
  
  await sendEmail(recipientEmail, {
    subject: `Weekly Stats: ${data.eventName}`,
    body: `
      Your event received:
      - ${data.metrics.clickCount} total views
      - ${data.metrics.outboundClickCount} link clicks
      - ${data.metrics.calendarSyncCount} calendar adds
    `
  });
}