> ## Documentation Index
> Fetch the complete documentation index at: https://docs.capedigital.co.ke/llms.txt
> Use this file to discover all available pages before exploring further.

# Air rate by bulletin slot

> Powers the **Monthly bulletin air rate by TV/Radio slot** bar chart on the **Bulletins** screen and the identical chart on the **Content analytics** screen.

Slot order in the response matches broadcast chronology (morning → midday → afternoon → evening → late_night → breaking) so the frontend can render bars in the correct sequence without sorting.

`air_rate_pct` excludes `pending` slots from the denominator — it is `aired / (aired + not_aired)`, reflecting actual broadcast outcome rather than total scheduled stories.



## OpenAPI

````yaml /openapi/content.yaml get /api/v1/analytics/bulletins/air-rate
openapi: 3.0.3
info:
  title: Content Service API
  version: 1.0.0
  description: |2-

        **Content Service API** - Comprehensive content(story) and management system.
        
servers:
  - url: https://api.capedigital.co.ke/content
    description: Production
  - url: http://localhost:8000
    description: Local
security: []
paths:
  /api/v1/analytics/bulletins/air-rate:
    get:
      tags:
        - Bulletin Analytics
      summary: Air rate by bulletin slot
      description: >-
        Powers the **Monthly bulletin air rate by TV/Radio slot** bar chart on
        the **Bulletins** screen and the identical chart on the **Content
        analytics** screen.


        Slot order in the response matches broadcast chronology (morning →
        midday → afternoon → evening → late_night → breaking) so the frontend
        can render bars in the correct sequence without sorting.


        `air_rate_pct` excludes `pending` slots from the denominator — it is
        `aired / (aired + not_aired)`, reflecting actual broadcast outcome
        rather than total scheduled stories.
      operationId: analytics_bulletins_air_rate_list
      parameters:
        - in: query
          name: period
          schema:
            type: string
          description: |-
            Period string. Accepted formats:
            - `2026-05` — calendar month
            - `Q2-2026` — quarter (Q1–Q4)
            - `YTD-2026` — year to date
          required: true
        - in: query
          name: platform
          schema:
            type: string
            enum:
              - radio
              - television
          description: Broadcast platform. One of `television` (default) or `radio`.
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AirRateBySlot'
              examples:
                May2026—TV:
                  value:
                    - - slot: morning
                        platform: television
                        total_slots: 186
                        aired: 145
                        not_aired: 32
                        pending: 9
                        air_rate_pct: '81.9'
                      - slot: midday
                        platform: television
                        total_slots: 180
                        aired: 144
                        not_aired: 28
                        pending: 8
                        air_rate_pct: '83.7'
                      - slot: afternoon
                        platform: television
                        total_slots: 175
                        aired: 124
                        not_aired: 44
                        pending: 7
                        air_rate_pct: '73.8'
                      - slot: evening
                        platform: television
                        total_slots: 210
                        aired: 172
                        not_aired: 30
                        pending: 8
                        air_rate_pct: '85.1'
                      - slot: late_night
                        platform: television
                        total_slots: 165
                        aired: 125
                        not_aired: 35
                        pending: 5
                        air_rate_pct: '78.1'
                  summary: May 2026 — TV
          description: ''
      security:
        - bearerAuth: []
components:
  schemas:
    AirRateBySlot:
      type: object
      properties:
        slot:
          type: string
        platform:
          type: string
        total_slots:
          type: integer
        aired:
          type: integer
        not_aired:
          type: integer
        pending:
          type: integer
        air_rate_pct:
          type: string
          format: decimal
          pattern: ^-?\d{0,4}(?:\.\d{0,1})?$
          nullable: true
      required:
        - air_rate_pct
        - aired
        - not_aired
        - pending
        - platform
        - slot
        - total_slots
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Enter your JWT token in the format: Bearer <token>'

````