beehiiv

beehiiv Ad Network Reports API

The Ad Network Reports API from beehiiv — 3 operation(s) for ad network reports.

Documentation GitHub OpenAPI

Business capability

Advertising Revenue Reporting BC-3760.60

Operations 3

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

GET /publications/{publicationId}/ad_network/reports List ad performance and payment reports · Get ad network reports OAuth Scope: posts:read #

Ask an LLM

“Where can I see per-ad performance and payment reports for my newsletter?”

“Can I pull ad network reports for just last month's date range?”

Tell an agent

List ad network reports for publication {publication} between {start_date} and {end_date}.

Show page {page} of the ad payment reports for {publication}.

GET /publications/{publicationId}/ad_network/reports/summaries Summarize ad revenue for one publication · Get ad network report summary OAuth Scope: posts:read #

Ask an LLM

“What is the total ad revenue for one of my newsletters this quarter?”

“Can I get a single aggregate of ad performance for one publication?”

Tell an agent

Summarize ad network revenue and performance for publication {publication}.

Give me the ad revenue total for {publication} from {start_date} to {end_date}.

GET /ad_network/reports/summaries Summarize ad revenue across all publications · Get account ad network report summary OAuth Scope: posts:read #

Ask an LLM

“How much ad revenue did my whole account earn across every newsletter?”

“Is there an account-wide rollup of ad network performance for all my publications?”

Tell an agent

Show my account-wide ad network summary across all publications.

Total the ad revenue across every publication I own from {start_date} to {end_date}.

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/beehiiv:beehiiv-ad-network-reports-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: Reference Ad Network Reports API
  version: 1.0.0
servers:
- url: https://api.beehiiv.com/v2
  description: Default
tags:
- name: Ad Network Reports
paths:
  /publications/{publicationId}/ad_network/reports:
    get:
      operationId: index
      summary: 'Get ad network reports OAuth Scope: posts:read'
      description: 'This feature is currently in beta and the API is subject to change.


        Retrieve advertisement performance and payment reports for the publication.'
      tags:
      - Ad Network Reports
      parameters:
      - name: publicationId
        in: path
        description: The prefixed ID of the publication object.
        required: true
        schema:
          $ref: '#/components/schemas/type_ids_PublicationId'
      - name: limit
        in: query
        description: A limit between 1 and 100. Defaults to 10.
        required: false
        schema:
          type: integer
      - name: page
        in: query
        description: The page of reports to return. Defaults to 1.
        required: false
        schema:
          type: integer
      - name: start_date
        in: query
        description: Include reports for advertisements sent on or after this date in `YYYY-MM-DD` format.
        required: false
        schema:
          type: string
          format: date
      - name: end_date
        in: query
        description: Include reports for advertisements sent on or before this date in `YYYY-MM-DD` format.
        required: false
        schema:
          type: string
          format: date
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_ad_network_reports_AdNetworkReportsGetResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '401':
          description: Unauthorized. The API key or OAuth access token is missing, invalid, or expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '404':
          description: Resource Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
  /publications/{publicationId}/ad_network/reports/summaries:
    get:
      operationId: summary
      summary: 'Get ad network report summary OAuth Scope: posts:read'
      description: 'This feature is currently in beta and the API is subject to change.


        Retrieve aggregate advertisement performance and revenue for a publication.'
      tags:
      - Ad Network Reports
      parameters:
      - name: publicationId
        in: path
        description: The prefixed ID of the publication object.
        required: true
        schema:
          $ref: '#/components/schemas/type_ids_PublicationId'
      - name: start_date
        in: query
        description: Include reports for advertisements sent on or after this date in `YYYY-MM-DD` format.
        required: false
        schema:
          type: string
          format: date
      - name: end_date
        in: query
        description: Include reports for advertisements sent on or before this date in `YYYY-MM-DD` format.
        required: false
        schema:
          type: string
          format: date
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_ad_network_reports_AdNetworkReportSummary'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '401':
          description: Unauthorized. The API key or OAuth access token is missing, invalid, or expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '404':
          description: Resource Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
  /ad_network/reports/summaries:
    get:
      operationId: account-summary
      summary: 'Get account ad network report summary OAuth Scope: posts:read'
      description: 'This feature is currently in beta and the API is subject to change.


        Retrieve one account-wide aggregate of advertisement performance and revenue across accessible publications.'
      tags:
      - Ad Network Reports
      parameters:
      - name: start_date
        in: query
        description: Include reports for advertisements sent on or after this date in `YYYY-MM-DD` format.
        required: false
        schema:
          type: string
          format: date
      - name: end_date
        in: query
        description: Include reports for advertisements sent on or before this date in `YYYY-MM-DD` format.
        required: false
        schema:
          type: string
          format: date
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_ad_network_reports_AdNetworkReportSummary'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '401':
          description: Unauthorized. The API key or OAuth access token is missing, invalid, or expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
components:
  schemas:
    type_ad_network_reports_AdNetworkReportsGetResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/type_ad_network_reports_AdNetworkReport'
          description: Advertisement performance and payment reports for the publication.
        limit:
          type: integer
          description: The maximum number of reports returned.
        page:
          type: integer
          description: The page number returned.
        total_results:
          type: integer
          description: The total number of reports.
        total_pages:
          type: integer
          description: The total number of pages.
      required:
      - data
      - limit
      - page
      - total_results
      - total_pages
      title: AdNetworkReportsGetResponse
    type_ids_PublicationId:
      type: string
      description: The prefixed ID of the publication.
      title: PublicationId
    type_ad_network_reports_AdNetworkReport:
      type: object
      properties:
        publication_id:
          $ref: '#/components/schemas/type_ids_PublicationId'
          description: The prefixed ID of the publication that ran the advertisement.
        post_id:
          $ref: '#/components/schemas/type_ids_PostId'
          description: The prefixed ID of the post containing the advertisement.
        ad_link_id:
          type: string
          description: The ID used to attribute engagement events to the advertisement.
        opens:
          type: integer
          description: The approved number of unique opens.
        verified_clicks:
          type: integer
          description: The approved number of verified clicks.
        revenue:
          type: string
          description: The formatted revenue approved for payment.
        is_programmatic:
          type: boolean
          description: Whether the advertisement was placed through a programmatic ad slot instead of an on-demand offer.
      required:
      - publication_id
      - post_id
      - ad_link_id
      - opens
      - verified_clicks
      - revenue
      - is_programmatic
      title: AdNetworkReport
    type_ad_network_reports_AdNetworkReportSummaryMetrics:
      type: object
      properties:
        opens:
          type: integer
          description: The approved number of unique opens.
        verified_clicks:
          type: integer
          description: The approved number of verified clicks.
        revenue:
          type: string
          description: The formatted revenue approved for payment.
      required:
      - opens
      - verified_clicks
      - revenue
      title: AdNetworkReportSummaryMetrics
    type__ErrorDetail:
      type: object
      properties:
        message:
          type: string
        code:
          type: string
      required:
      - message
      - code
      title: ErrorDetail
    type_ids_PostId:
      type: string
      description: The prefixed ID of the post.
      title: PostId
    type__Error:
      type: object
      properties:
        status:
          type: integer
        statusText:
          type: string
        errors:
          type: array
          items:
            $ref: '#/components/schemas/type__ErrorDetail'
      required:
      - status
      - statusText
      - errors
      description: The top level error response.
      title: Error
    type_ad_network_reports_AdNetworkReportSummary:
      type: object
      properties:
        publication_id:
          $ref: '#/components/schemas/type_ids_PublicationId'
          description: The prefixed publication ID. Omitted from account-wide summaries.
        opens:
          type: integer
          description: The total approved number of unique opens.
        verified_clicks:
          type: integer
          description: The total approved number of verified clicks.
        revenue:
          type: string
          description: The total formatted revenue approved for payment.
        oda:
          $ref: '#/components/schemas/type_ad_network_reports_AdNetworkReportSummaryMetrics'
          description: Metrics for advertisements accepted as on-demand offers.
        programmatic:
          $ref: '#/components/schemas/type_ad_network_reports_AdNetworkReportSummaryMetrics'
          description: Metrics for advertisements placed through programmatic ad slots.
      required:
      - opens
      - verified_clicks
      - revenue
      - oda
      - programmatic
      title: AdNetworkReportSummary
  securitySchemes:
    BearerAuthScheme:
      type: http
      scheme: bearer

beehiiv Ad Network Reports API

Operations 3

Documentation

Specifications

Schemas & Data

Work with this as data

MCP server

Tools for apis

Call it yourself

Get an API key

OpenAPI Specification