---
title: "Billboards"
method: GET
path: "/api/billboards"
tags: ["billboards"]
---

# Billboards

`GET /api/billboards`

Retrieve a list of all billboards configured in the system.

        ### Billboards Overview:
        - Billboards are custom promotional ads, notification banners, or call-to-actions shown on the Forem website.
        - Requires administrative privileges.
        - Returned objects include layout code, scheduling parameters, geo-targeting configurations, and custom target audience segment associations.

## Response `200`

successful

- Billboard[]
  - `id` integer — The ID of the Billboard
  - `name` string, required — For internal use, helps distinguish ads from one another
  - `body_markdown` string, required — The text (in markdown) of the ad (required)
  - `approved` boolean — Ad must be both published and approved to be in rotation
  - `published` boolean — Ad must be both published and approved to be in rotation
  - `expires_at` string, date-time, nullable — Timestamp when the billboard expires. After this time, the billboard will automatically be marked as not approved.
  - `organization_id` integer, nullable — Identifies the organization to which the ad belongs
  - `creator_id` integer, nullable — Identifies the user who created the ad.
  - `placement_area` 'sidebar_left' | 'sidebar_left_2' | 'sidebar_right' | 'sidebar_right_second' | 'sidebar_right_third' | 'feed_first' | 'feed_second' | 'feed_third' | 'home_hero' | 'footer' | 'page_fixed_bottom' | 'post_fixed_bottom' | 'post_body_bottom' | 'post_sidebar' | 'post_comments' | 'post_comments_mid' | 'digest_first' | 'digest_second', required — Identifies which area of site layout the ad can appear in
  - `tag_list` string — Tags on which this ad can be displayed (blank is all/any tags)
  - `exclude_article_ids` string, nullable — Articles this ad should *not* appear on (blank means no articles are disallowed, and this ad can appear next to any/all articles). Comma-separated list of integer Article IDs
  - `audience_segment_id` integer — Specifies a specific audience segment who will see this billboard
  - `audience_segment_type` 'manual' | 'trusted' | 'posted' | 'no_posts_yet' | 'dark_theme' | 'light_theme' | 'no_experience' | 'experience1' | 'experience2' | 'experience3' | 'experience4' | 'experience5' — Specifies a group of users who will see this billboard (must match audience_segment_id if both provided)
  - `target_geolocations` string[] — Locations to show this billboard in (blank means it will be shown in all locations). Specified as a comma-separated list or array of ISO 3166-2 country and optionally region codes)
  - `display_to` 'all' | 'logged_in' | 'logged_out' — Potentially limits visitors to whom the ad is visible
  - `type_of` 'in_house' | 'community' | 'external' — Types of the billboards: in_house (created by admins), community (created by an entity, appears on entity's content), external ( created by an entity, or a non-entity, can appear everywhere)

## Other responses

- `401` — unauthorized

## Changes

> 59 revisions in range; 34 could not be searched.

- **2026-07-13** (v1) `189b62b952ea` — 1 breaking
  - removed the media type `application/json` for the response with the status `401`
- **2023-01-10** (v1) `754f8b25f815` — 1 breaking
  - api path removed without deprecation

[Change history](https://skmtc.dev/forem/apis/forem-api-v1/changes/api/billboards/get.md)

---

[API](https://skmtc.dev/forem/apis/forem-api-v1.md) · [All operations](https://skmtc.dev/forem/apis/forem-api-v1/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/forem/forem-api-v1/revisions/1f64f71fc2a7/schema)