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

# Brand visibility report

> Visibility, sentiment, and position metrics per brand.

## POST /reports/brands

Returns brand visibility metrics for the given date range: visibility percentage, sentiment, and average position.

**Endpoint:** `POST https://api.geoark.ai/api/customer/v1/reports/brands`

### Request

Send your API key in the `X-API-Key` header or as `api_key` query parameter (see [Authentication](/docs/api-reference/authentication)).

**Body (JSON, all optional):**

| Icon | Field        | Type   | Description                                    |
| :--: | ------------ | ------ | ---------------------------------------------- |
|  🏷️ | `brand_id`   | string | Filter by brand ID. Omit for all brands.       |
|  📅  | `start_date` | string | Start date `YYYY-MM-DD`. Default: 30 days ago. |
|  📅  | `end_date`   | string | End date `YYYY-MM-DD`. Default: today.         |
|  🔢  | `limit`      | number | Max items (1–10000). Default: 1000.            |
|  ↩️  | `offset`     | number | Pagination offset. Default: 0.                 |

<Info>
  **`project_id`** — Alias for `brand_id` (for integration compatibility). Use one or the other.
</Info>

### Response

```json theme={null}
{
  "data": [
    {
      "brand": { "id": "...", "name": "Acme Inc" },
      "visibility": 72.5,
      "visibility_count": 29,
      "visibility_total": 40,
      "sentiment": 68.2,
      "sentiment_count": 29,
      "position": 2.1,
      "position_count": 29
    }
  ],
  "total": 1
}
```

### Status codes

* **200** — Success
* **400** — Validation error (e.g. invalid date format)
* **401** — Invalid or missing API key
* **402** — Paid subscription required (Custom plan)


## OpenAPI

````yaml openapi-customer.json post /reports/brands
openapi: 3.0.3
info:
  title: GeoArk AI Customer API
  description: >-
    Report API for custom users and integrations. Use your API key (Dashboard →
    API Keys) to pull brand visibility, queries, and mentions. Use for automated
    reports, dashboards, and alerts.
  version: 1.0.0
  contact:
    name: GeoArk AI
    url: https://geoark.ai
servers:
  - url: https://api.geoark.ai/api/customer/v1
    description: GeoArk AI API
security:
  - APIKeyHeader: []
  - APIKeyQuery: []
tags:
  - name: Reports
    description: Report endpoints for visibility data (API key required).
paths:
  /reports/brands:
    post:
      tags:
        - Reports
      summary: Brand visibility report
      description: >-
        Returns visibility, sentiment, and position metrics per brand for the
        date range.
      operationId: postReportsBrands
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReportParams'
      responses:
        '200':
          description: Brand visibility report
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/BrandReportRow'
                  total:
                    type: integer
        '400':
          description: Validation error (e.g. invalid date format).
        '401':
          description: Invalid or missing API key.
        '402':
          description: Paid subscription required (Custom plan).
components:
  schemas:
    ReportParams:
      type: object
      properties:
        brand_id:
          type: string
          description: Filter by brand ID. Omit for all brands.
        project_id:
          type: string
          description: Alias for brand_id (integration compatibility).
        start_date:
          type: string
          format: date
          description: 'Start date (YYYY-MM-DD). Default: 30 days ago.'
        end_date:
          type: string
          format: date
          description: 'End date (YYYY-MM-DD). Default: today.'
        limit:
          type: integer
          default: 1000
          minimum: 1
          maximum: 10000
          description: Max items to return.
        offset:
          type: integer
          default: 0
          minimum: 0
          description: Offset for pagination.
    BrandReportRow:
      type: object
      properties:
        brand:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
        visibility:
          type: number
          description: Visibility percentage (0–100).
        visibility_count:
          type: integer
        visibility_total:
          type: integer
        sentiment:
          type: number
          description: Average sentiment score.
        sentiment_count:
          type: integer
        position:
          type: number
          description: Average position when mentioned.
        position_count:
          type: integer
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key from Dashboard → API Keys (Custom plan).
    APIKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: API key as query parameter (optional).

````