> ## 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.

# Mentions

> Brand mentions with source, snippet, platform, and sentiment.

## POST /reports/mentions

Returns brand mentions with source type, URL, title, snippet, platform, and sentiment. Optional date filter.

Each mention includes the **prompt that was asked** (`query.queryText`) — the query that led to this mention — so you can see which prompt surfaced each result.

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

### 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):**

| Field        | Type   | Description                              |
| ------------ | ------ | ---------------------------------------- |
| `brand_id`   | string | Filter by brand ID. Omit for all brands. |
| `project_id` | string | Alias for `brand_id`.                    |
| `start_date` | string | Start date `YYYY-MM-DD`.                 |
| `end_date`   | string | End date `YYYY-MM-DD`.                   |
| `limit`      | number | Max items. Default: 1000.                |
| `offset`     | number | Pagination offset. Default: 0.           |

### Response

Each object in `data` includes the mention details plus **query** — with **queryText** (the prompt that was asked), `id`, and `platform` (CHATGPT, CLAUDE, GEMINI, PERPLEXITY, GROK, DEEPSEEK, or LLAMA) — so you know which query produced the mention.

```json theme={null}
{
  "data": [
    {
      "id": "...",
      "brand": { "id": "...", "name": "Acme Inc" },
      "sourceType": "ARTICLE",
      "sourceName": "Tech Review",
      "sourceUrl": "https://...",
      "title": "Best tools for 2025",
      "snippet": "Acme Inc is recommended for...",
      "platform": "CHATGPT",
      "sentiment": "POSITIVE",
      "discoveredAt": "2025-02-20T14:00:00.000Z",
      "query": { "id": "...", "queryText": "best CRM", "platform": "CHATGPT" }
    }
  ],
  "total": 15
}
```

### Status codes

* **200** — Success
* **400** — Validation error
* **401** — Invalid or missing API key
* **402** — Paid subscription required (Custom plan)


## OpenAPI

````yaml openapi-customer.json post /reports/mentions
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/mentions:
    post:
      tags:
        - Reports
      summary: Mentions report
      description: >-
        Returns brand mentions with source, snippet, platform, and sentiment.
        Optional date filter.
      operationId: postReportsMentions
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReportParams'
      responses:
        '200':
          description: Mentions report
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                  total:
                    type: integer
        '400':
          description: Validation error.
        '401':
          description: Invalid or missing API key.
        '402':
          description: Paid subscription required.
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.
  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).

````