These endpoints will allow you to report how tracks are used in your application.
openapi: 3.0.1
info:
title: Partner Content Assets Reporting API
version: 0.1.17
description: These endpoints allows your application to upload assets such as images or audio.
servers:
- url: https://partner-content-api.epidemicsound.com
description: Epidemic Sound Content API
tags:
- name: Reporting
description: These endpoints will allow you to report how tracks are used in your application.
paths:
/v0/analytics/report:
post:
tags:
- Reporting
summary: Report usage in bulk
description: "This endpoint should be used when you want to bulk report events to Epidemic Sound. We currently support the following events:\ntrackPreviewed, trackDownloaded and tracksExported. Note that the limit for number of events per request is limited to 100.\n Also note that for events containing the field trackIds, the limit for number of trackIds per event is 50. \n Events may not contain a timestamp older than 7 days ago."
operationId: POST_Analytics_Report
requestBody:
description: Analytics report
content:
application/json:
schema:
$ref: '#/components/schemas/AnalyticsReportRequest'
example:
events:
- userId: '123'
timestamp: '2026-05-11T07:45:47.634091607Z'
userConnected: false
analyticsEvent:
trackId: '12345'
type: trackPreviewed
- userId: '456'
timestamp: '2026-05-11T07:45:47.634810417Z'
userConnected: true
analyticsEvent:
trackId: '12345'
format: mp3
quality: normal
type: trackDownloaded
- userId: '456'
timestamp: '2026-05-11T07:45:47.635468127Z'
analyticsEvent:
trackIds:
- '12345'
platform: YOUTUBE
type: tracksExported
responses:
'200':
description: Usage report response
content:
application/json:
schema:
$ref: '#/components/schemas/AnalyticsReportResponse'
example:
batchId: '12345'
eventsCount: 10
'401':
description: Unauthorized. Most likely your access token has expired.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageResponse'
example:
message: Invalid credentials
'429':
description: Rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageResponse'
example:
message: Rate limit exceeded
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageResponse'
example:
message: Bad request
security:
- PartnerAuth: []
- ApiKeyAuth: []
/v0/usage:
post:
tags:
- Reporting
summary: Report usage
description: 'The usage endpoint lets you report when a user exports their content to social media or downloads the content file to their device.
You can specify which platform (YouTube, Twitch, Instagram, Facebook, TikTok, Twitter or Other) they export the file to. Use the platform `local` if the user downloads the content to their device.
This data is used for attribution and analytics purposes as well as to improve personalization.'
operationId: POST_Use
requestBody:
description: Usage report
content:
application/json:
schema:
$ref: '#/components/schemas/TrackUsageRequest'
example:
eventType: EXPORTED
platform: OTHER
trackIds:
- trackid1
- trackid2
other: OptionalValueForWhenNoMatchingPlatformEnum
responses:
'200':
description: Usage report response
content:
application/json:
schema:
$ref: '#/components/schemas/MessageResponse'
example:
message: Ok
'401':
description: Unauthorized. Most likely your access token has expired.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageResponse'
example:
message: Invalid credentials
'429':
description: Rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageResponse'
example:
message: Rate limit exceeded
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/MessageResponse'
example:
message: Bad request
security:
- UserAuth: []
- EpidemicSoundConnectAuth: []
- ApiKeyAuth: []
components:
schemas:
TracksExportedEvent:
type: object
properties:
trackIds:
type: array
items:
type: string
platform:
type: string
enum:
- YOUTUBE
- TWITTER
- TWITCH
- FACEBOOK
- INSTAGRAM
- TIKTOK
- OTHER
- LOCAL
type:
type: string
enum:
- tracksExported
AnalyticsReportResponse:
required:
- batchId
- eventsCount
type: object
properties:
batchId:
type: string
eventsCount:
type: integer
format: int32
AnalyticsReportEvent:
type: object
properties:
userId:
type: string
timestamp:
type: string
format: date-time
userConnected:
type: boolean
nullable: true
analyticsEvent:
$ref: '#/components/schemas/AnalyticsEvent'
Error:
required:
- key
- messages
type: object
properties:
key:
type: string
description: Error key
messages:
type: array
description: Error messages
items:
type: string
description: Error messages
MessageResponse:
required:
- message
type: object
properties:
message:
type: string
description: Human readable message
errors:
type: array
items:
$ref: '#/components/schemas/Error'
AnalyticsEvent:
type: object
oneOf:
- $ref: '#/components/schemas/TrackPreviewedEvent'
- $ref: '#/components/schemas/TrackDownloadedEvent'
- $ref: '#/components/schemas/TracksExportedEvent'
TrackUsageRequest:
required:
- platform
- trackIds
type: object
properties:
eventType:
type: string
enum:
- EXPORTED
platform:
type: string
enum:
- YOUTUBE
- TWITTER
- TWITCH
- FACEBOOK
- INSTAGRAM
- TIKTOK
- OTHER
- LOCAL
trackIds:
type: array
items:
type: string
other:
type: string
nullable: true
TrackDownloadedEvent:
type: object
properties:
trackId:
type: string
format:
type: string
enum:
- mp3
- hls
- hls_with_cookie
quality:
type: string
enum:
- normal
- high
type:
type: string
enum:
- trackDownloaded
TrackPreviewedEvent:
type: object
properties:
trackId:
type: string
type:
type: string
enum:
- trackPreviewed
AnalyticsReportRequest:
required:
- events
type: object
properties:
events:
type: array
items:
$ref: '#/components/schemas/AnalyticsReportEvent'
securitySchemes:
ApiKeyAuth:
type: http
description: 'API key authentication for server-to-server communication.
Pass your API key as a Bearer token in the Authorization header.
API keys are prefixed with `epidemic_live_`.
> **Example Header:** `Authorization: Bearer epidemic_live_your-api-key`'
scheme: bearer
PartnerAuth:
type: http
description: 'Partner authentication is handled with short lived partner access tokens.
Use your api credentials to request these tokens.
The access token is of JWT format and should be passed in a header with your API requests:
> **Example Header:** `Authorization: Bearer your-partner-token`'
scheme: Bearer
UserAuth:
type: http
description: "User authentication is handled with short lived user access tokens.\n Use a partner token to request these tokens.\n The access token is of JWT format and should be passed in a header with your API requests:\n\n > **Example Header:** `Authorization: Bearer a-user-token`"
scheme: Bearer
EpidemicSoundConnectAuth:
type: oauth2
description: 'For users signing in with an Epidemic Sound account, user authentication is
handled with OpenID Connect, which is a layer on top of OAuth 2.0.
> **Example Header:** `Authorization: Bearer es-connect-token`'
flows:
authorizationCode:
authorizationUrl: https://login.epidemicsound.com/auth/realms/accounts/protocol/openid-connect/auth
tokenUrl: https://login.epidemicsound.com/auth/realms/accounts/protocol/openid-connect/token
scopes: {}