Skip to main content

Report usage

Report track usage to Epidemic Sound when users export their content to social media platforms or download content files to their device. This data is used for billing & analytics-purposes.

Music tracks only

Usage reporting is for music tracks. It doesn't cover sound effects usage.

Unlike /v0/usage, the bulk /v0/analytics/report endpoint doesn't validate track IDs against the catalog — unrecognized IDs are silently dropped rather than rejected, so a 200 response doesn't guarantee every ID was recorded.

When to report usage​

Report usage when:

  • User exports their content to a social media platform
  • User downloads the complete video+music composition to their device (use platform LOCAL)

Do not report usage for:

  • Preview playback during browsing
  • Your application is downloading tracks (such as music used in a video editor)

Per-user reporting​

Use the usage endpoint for individual usage events. The x-partner-user-id header identifies which end user is using the track for per-user analytics and billing attribution:

POST /v0/usage
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
x-partner-user-id: user123

{
  "eventType": "EXPORTED",
  "platform": "YOUTUBE",
  "trackIds": ["1a8d1f60-398c-3cec-83bf-4ed5efd3b851"]
}

trackIds is an array — batch multiple tracks used together in one call instead of one request per track.

Supported platforms:

  • YOUTUBE
  • TWITTER
  • TWITCH
  • FACEBOOK
  • INSTAGRAM
  • TIKTOK
  • OTHER
  • LOCAL (for downloads to device)

Rate limiting: Usage reporting does not count against the per-user weekly rate limits - only audio delivery endpoints (download, stream, HLS) count toward those limits.

Bulk reporting​

Use the bulk reporting endpoint for batch processing. Each event needs a timestamp and an analyticsEvent object with a type discriminator — trackPreviewed, trackDownloaded, or tracksExported:

POST /v0/analytics/report
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "events": [
    {
      "userId": "user123",
      "timestamp": "2026-09-22T10:00:00Z",
      "analyticsEvent": {
        "type": "tracksExported",
        "trackIds": ["1a8d1f60-398c-3cec-83bf-4ed5efd3b851"],
        "platform": "YOUTUBE"
      }
    },
    {
      "userId": "user456",
      "timestamp": "2026-09-22T10:01:00Z",
      "analyticsEvent": {
        "type": "tracksExported",
        "trackIds": ["2b9e2d71-499d-4dfd-94cd-5fe6dde4c962"],
        "platform": "TIKTOK"
      }
    }
  ]
}

Batch limits: Up to 100 events per request, and up to 50 track IDs per event. Each event's timestamp must be in the past and no more than 7 days old.

Backend authentication required for bulk reporting

The bulk reporting endpoint must be called from your backend using your API key. For client-side per-user reporting, use the /v0/usage endpoint with the x-partner-user-id header.