Partner API Admin

The Partner API provides external access to ad analytics data. It is designed for partners who need to pull event-level and summary data programmatically.

Endpoints

GET /api/partners/:id/ad-analytics/events

Returns Log Level Data (LLD) events with pagination.

Query Parameters:

Parameter	Required	Description
`start_date`	Yes	Start date (YYYY-MM-DD)
`end_date`	Yes	End date (YYYY-MM-DD)
`hour`	No	Filter by hour (0—23) for large datasets
`page`	No	Page number (default: 1)
`per_page`	No	Results per page (default: 1000, max: 10000)

Example:

curl "https://api.nucleusanalytica.com/api/partners/PARTNER_ID/ad-analytics/events?start_date=2026-05-01&end_date=2026-05-01&hour=14&page=1&per_page=5000" \
  -H "Authorization: Bearer YOUR_API_KEY"

For large datasets (millions of records per day), use hour-level filtering to break requests into manageable chunks. Query each hour separately (0—23) to avoid pagination limits.

GET /api/partners/:id/ad-analytics/summary

Returns aggregated metrics for a date range.

Query Parameters:

Parameter	Required	Description
`start_date`	Yes	Start date (YYYY-MM-DD)
`end_date`	Yes	End date (YYYY-MM-DD)
`group_by`	No	Group results by `day`, `campaign`, or `demand_tag`

Example:

curl "https://api.nucleusanalytica.com/api/partners/PARTNER_ID/ad-analytics/summary?start_date=2026-05-01&end_date=2026-05-15&group_by=day" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /api/partners/:id/ad-analytics/dates

Returns the list of dates that have data available.

Example:

curl "https://api.nucleusanalytica.com/api/partners/PARTNER_ID/ad-analytics/dates" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "dates": ["2026-05-01", "2026-05-02", "2026-05-03", ...]
}

POST /api/partners/:id/ad-analytics/bulk-export

For large dataset extraction. Returns a download URL for the complete dataset.

Body:

{
  "start_date": "2026-05-01",
  "end_date": "2026-05-01",
  "format": "csv"
}

The response includes a URL to download the exported file. Large exports are processed asynchronously.

Rate Limits

Partner API requests are limited to 1,000 requests per hour per API key. Use bulk export for large data extractions instead of paginating through millions of events.

Partition-Aware Queries

Data is stored in monthly partitions. Queries that span multiple months are handled automatically — you do not need to adjust your queries for partition boundaries.

Authentication Webhooks