Back to Developer Documentation

Show Metrics API

REST endpoints for retrieving show revenue and download metrics.

Base URL

https://api.studio.inlet.fm

Authentication

All endpoints require authentication via the Authorization header:

Authorization: Token <API_KEY>

Requests without a valid token return 401 Unauthorized. Rate limiting is applied per API key.

Common Parameters

  • podcastId (path, required): ID of your show
  • fromDate (query, required): ISO 8601 date (e.g. 2025-01-01 or 2025-01-01T00:00:00Z)
  • toDate (query, required): ISO 8601 date. Must be >= fromDate

    • Validation errors return 400 with a structured error payload.

    Endpoints

    1. Revenue Metrics

    GET https://api.studio.inlet.fm/api/v1/podcasts/:podcastId/revenue

    Returns actualized creator revenue and ad-fill metrics for the shows revenue metrics over the date range, filtered to closed billing status.

    Response Shape

  • revenue (number): Revenue paid to the creator for the period
  • eCPM (number | null): Effective CPM based on revenueToCreator. null if there are no delivered impressions
  • fillRate (number | null): Fraction of requested impressions that were filled (0–1). null if the denominator is zero or the show is not setup yet

    • Empty-data Behavior

  • If show hasn't been setup for revenue reporting yet → { revenue: 0, eCPM: null, fillRate: null }

    • Example Request

    curl "https://api.studio.inlet.fm/api/v1/podcasts/66ab0123cdef456789abcdef/revenue?fromDate=2025-01-01&toDate=2025-03-31" \
  -H "Authorization: Token your-api-key-here"

    Response

    {
  "success": true,
  "data": {
    "revenue": 1234.5678,
    "eCPM": 18.9421,
    "fillRate": 0.8734
  }
}

    2. Download Metrics

    GET https://api.studio.inlet.fm/api/v1/podcasts/:podcastId/downloads

    Returns total show downloads for the date range.

    Response Shape

  • downloads (number): Total downloads for the show across the date range (sum of daily totals)

    • Empty-data Behavior

  • If show hasn't been setup for reporting metrics → { downloads: 0 }
  • No matching records in range → { downloads: 0 }

    • Example Request

    curl "https://api.studio.inlet.fm/api/v1/podcasts/66ab0123cdef456789abcdef/downloads?fromDate=2025-01-01&toDate=2025-03-31" \
  -H "Authorization: Token your-api-key-here"

    Response

    {
  "success": true,
  "data": {
    "downloads": 543210
  }
}

    TypeScript Types

    export interface ShowRevenueSummary {
    revenue: number;
    eCPM: number | null;
    fillRate: number | null;
}

export interface ShowDownloadsSummary {
    downloads: number;
}

export interface ApiSuccess<T> {
    success: true;
    data: T;
}

    Error Responses

    All endpoints return consistent error responses:

    Common HTTP Status Codes

  • 400: Bad Request (invalid podcastId, missing or malformed dates)
  • 401: Unauthorized (missing or invalid API key)
  • 403: Forbidden (API key does not have access to this show)
  • 404: Not Found (show not found)
  • 500: Internal Server Error

    • Migration Notes (Breaking Changes)

    If you were consuming earlier versions of these endpoints, the response shapes have been slimmed.

    /revenue — removed fields

    totalRevenue, revenueToCreator, revenueToAdPartner, impressionsBooked, impressionsDelivered, averageCpm, averageEcpm, lineItemCount, byPeriod, openAmount, closedAmount.

    Mapping:

  • revenue replaces revenueToCreator
  • eCPM replaces averageEcpm
  • fillRate is newly exposed here (previously only returned by /downloads)

    • /downloads — removed fields

    totalDownloads, totalAvailability, totalPlaceableCapacity, averageAdslotCount, orderWaterfallFill, backfillWaterfallFill, priorityVastWaterfallFill, utwVastWaterfallFill, promoWaterfallFill, fillRate, recordCount.

    Mapping:

  • downloads replaces totalDownloads
  • fillRate has moved to /revenue

    • Notes

  • eCPM and fillRate can independently be null — render a placeholder (e.g. —) rather than assuming numeric values.
  • revenue and eCPM are rounded to 4 decimal places server-side.
  • fillRate is a fraction in the range 0..1, not a percentage. Multiply by 100 if you need to display it as %.