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

# Get Brand Analytics

> Brand-level running-ads distribution and creative velocity; id must be a page_id / ad_library_id.

Get analytics for a brand — running-ads distribution and creative velocity. A successful call returns **one row per day** in `data[]` (`date`, `active_count`, `inactive_count`, and per-format counts). Optionally scope with `start_date` / `end_date` and `order`.

⚠️ **The `id` parameter must be a page\_id / `ad_library_id`, NOT a Foreplay `brand_id`.** Passing a `brand_id` returns **HTTP 406**. Get the `ad_library_id` from [`get_foreplay-getbrandsbydomain`](/docs/api-reference/foreplay/get_foreplay-getbrandsbydomain) first. Flow: `getBrandsByDomain(domain)` → `ad_library_id` → `brand/analytics(id=ad_library_id)`.

⚠️ **Date window: the range between `start_date` and `end_date` must be ≤ 30 days.** A larger range returns **HTTP 406** `Date range too large`:

```json theme={null}
{"metadata":{"success":false,"status_code":406},"error":{"message":"Date range too large","max_allowed_days":"30 days"},"data":[]}
```

So this endpoint has **two** `406` cases: (1) a `brand_id` was passed instead of a page\_id / `ad_library_id`, and (2) the date window exceeds 30 days.

**Billing: $0.02625 per item returned in `data[]`; empty results and errors are not charged.** Because the response is one row per day, **each returned row is 1 billed item ($0.02625)** — a 30-day window can bill up to \~30 items, which matters for cost estimation. A `406` (either case) is not charged.

Example: resolve a domain first (e.g. `getBrandsByDomain?domain=nike.com` → `ad_library_id: "15087023444"`), then query analytics with that id: `GET /foreplay/brand/analytics?id=15087023444&start_date=2025-01-01&end_date=2025-01-30`.

Related: [`get_foreplay-getbrandsbydomain`](/docs/api-reference/foreplay/get_foreplay-getbrandsbydomain), [`get_foreplay-getadsbybrandid`](/docs/api-reference/foreplay/get_foreplay-getadsbybrandid), [`get_foreplay-discovery-ads`](/docs/api-reference/foreplay/get_foreplay-discovery-ads).


## OpenAPI

````yaml openapi/foreplay.json GET /foreplay/brand/analytics
openapi: 3.0.3
info:
  title: Foreplay API
  version: 1.0.0
  description: >-
    Foreplay ad creative intelligence routed through the AIsa gateway. Search a
    100M+ ad library, pull ads for known brands, resolve brands by domain, and
    get brand-level running-ads distribution and creative velocity analytics.
    All data endpoints are billed per item returned in `data[]` ($0.02625 /
    item); empty results and 4xx/5xx errors are not charged.
servers:
  - url: https://api.aisa.one/apis/v1
security:
  - BearerAuth: []
paths:
  /foreplay/brand/analytics:
    get:
      summary: Get Brand Analytics
      description: >-
        Get analytics for a brand (running-ads distribution, creative velocity)
        as a series of analytics rows. A successful call returns **one row per
        day** (`date`, `active_count`, `inactive_count`, and per-format counts).


        **Important:** the `id` parameter must be a page_id / `ad_library_id`
        (obtained from the `getBrandsByDomain` response), NOT a Foreplay
        `brand_id`. Passing a `brand_id` returns HTTP 406. Flow:
        `getBrandsByDomain(domain)` -> `ad_library_id` ->
        `brand/analytics(id=ad_library_id)`.


        **Date window:** the window between `start_date` and `end_date` must be
        ≤ 30 days. A larger range returns HTTP 406 `Date range too large`.


        **Cost estimation:** each returned row is 1 billed item ($0.02625).
        Because the response is one row per day, a 30-day window can bill up to
        ~30 items.


        Billed $0.02625 per item returned in `data[]` (1 credit per item); empty
        results and 4xx/5xx errors are not charged.
      operationId: get_brands_analytics
      parameters:
        - name: id
          in: query
          required: true
          description: >-
            Page ID or Brand ID. Brand IDs are 20-25 character alphanumeric
            strings with mixed case. Page IDs are numeric Facebook page
            identifiers.
          schema:
            type: string
        - name: start_date
          in: query
          required: false
          description: >-
            Start date (inclusive). Format: 'YYYY-MM-DD', 'YYYY-MM-DDTHH:MM:SS',
            or 'YYYY-MM-DD HH:MM:SS'. If you provide only the date (e.g.
            '2024-11-12'), it will be interpreted as '2024-11-12 00:00:00'. To
            get all ads from a specific day, set end_date to 'YYYY-MM-DD
            23:59:59' or to the next day at '00:00:00'. Examples:
            start_date=2024-11-12 00:00:00, end_date=2024-11-12 23:59:59. The
            window between start_date and end_date must be ≤ 30 days. A larger
            range returns HTTP 406 `Date range too large`.
          schema:
            type: string
        - name: end_date
          in: query
          required: false
          description: >-
            End date (inclusive). Format: 'YYYY-MM-DD', 'YYYY-MM-DDTHH:MM:SS',
            or 'YYYY-MM-DD HH:MM:SS'. If you provide only the date (e.g.
            '2024-11-12'), it will be interpreted as '2024-11-12 00:00:00'. To
            include all results for a given day, set end_date to 'YYYY-MM-DD
            23:59:59' or to the next day at '00:00:00'. Examples:
            start_date=2024-11-12 00:00:00, end_date=2024-11-12 23:59:59. The
            window between start_date and end_date must be ≤ 30 days. A larger
            range returns HTTP 406 `Date range too large`.
          schema:
            type: string
        - name: order
          in: query
          required: false
          description: >-
            Order of results: 'newest' (default), 'oldest', 'longest_running',
            or 'most_relevant'. Sorts ads by creation date, longest running
            duration, or relevance to the search query.
          schema:
            type: string
            default: newest
            enum:
              - newest
              - oldest
              - longest_running
              - most_relevant
      responses:
        '200':
          description: >-
            JSON envelope with `metadata` and a `data[]` array of analytics rows
            (one row per day, each with `date`, `active_count`,
            `inactive_count`, and per-format counts). Each row in `data[]`
            counts as one billed item.
          content:
            application/json:
              schema:
                type: object
              example:
                metadata:
                  success: true
                  status_code: 200
                  count: 2
                  cursor: null
                data:
                  - date: '2025-01-01'
                    active_count: 12
                    inactive_count: 3
                    video: 7
                    image: 5
                  - date: '2025-01-02'
                    active_count: 14
                    inactive_count: 2
                    video: 8
                    image: 6
                error: null
        '406':
          description: >-
            Not Acceptable. Returned in two cases: (1) the
            `start_date`–`end_date` window exceeds 30 days (`Date range too
            large`); or (2) a Foreplay `brand_id` was passed to `id` instead of
            a page_id / `ad_library_id`. Not charged.
          content:
            application/json:
              schema:
                type: object
              example:
                metadata:
                  success: false
                  status_code: 406
                error:
                  message: Date range too large
                  max_allowed_days: 30 days
                data: []
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: AISA API Key

````