Source: https://datafa.st/docs/api/website/mentions/list
Markdown source: https://datafa.st/docs/api/website/mentions/list.md
Description: Search stored X and Reddit mentions for one website.

# List mentions

`GET https://datafa.st/api/v1/mentions`

Search stored X and Reddit mentions for one website.

Required account-token permission: `analytics:read`.

## Query parameters

| Parameter | Type | Description |
|---|---|---|
| `startAt` / `endAt` | string | Supply together. Inclusive YYYY-MM-DD dates or ISO timestamps with Z/offset. Defaults to the last 30 calendar days, including today. |
| `timezone` | string | IANA timezone; defaults to the website timezone. Date-only bounds include the entire local day. |
| `q` | string | Case-insensitive text search, up to 200 characters. |
| `limit` | integer | Page size, 1–1000; default 100. |
| `offset` | integer | Rows to skip; default 0. |
| `order` | string | `desc` (newest first, default) or `asc`. |

Pagination returns `limit`, `offset`, `total`, and `hasMore`. Unknown or duplicate query parameters are rejected.

| Additional parameter | Type | Description |
|---|---|---|
| `websiteId` | string | Required with `dft_`; inferred from `df_`. |
| `platform` | string | `x` or `reddit`; omit for both. |

The `q` search matches post text, author name/username, URL, and subreddit. Relevance filtering and the Starter sample match the chart and happen before search, platform filtering, sorting, and pagination.

## Response

Each `data` item includes `id`, `websiteId`, `platform`, `timestamp` (UTC ISO), `text`, `url`, `author` (name, username, image), and `engagement`. X items also include `media` and `isRetweet`; Reddit items include `subreddit`. X engagement contains likes, replies, reposts, and quotes; Reddit contains score and comments.

`pagination.total` counts accessible matches after search. `meta.totalMentions` counts all relevant stored mentions in the date range before the plan cap/search. `meta.sampled` indicates withheld results; `meta.mentionLimit` is 3 for limited access and null for full access. `meta` also returns the resolved timezone and UTC date bounds. Starter responses include `meta.message` explaining that Starter provides a sample and `meta.upgradeUrl` linking to `https://datafa.st/dashboard/billing` to unlock all available mentions with Growth. These fields are present even for empty or filtered Starter results; Growth responses omit them.

MCP: `datafast_mentions_list` accepts the same parameters.

## Authentication

Use `Authorization: Bearer df_...` for one website, or `dft_...` with the required permission and website access. Notes always require `websiteId` in the path. Mention reads infer it from a website key; account tokens must provide the `websiteId` query parameter.

Existing website keys and `*` account tokens work automatically. For restricted account tokens, open [Account settings → API](/dashboard/settings?tab=api), expand your token, choose **Edit permissions**, and enable **Notes → Read / Write**. Save permissions to keep the same token and MCP connection. Only the signed-in token owner can edit permissions in the dashboard; no API or MCP operation can do this.

## Errors

Standard errors use `{ "status": "error", "error": { "code": 400, "message": "..." } }`. Expect `400` for invalid fields, dates, or IDs; `401` for invalid credentials; `403` for missing permissions or website access; `404` for a missing website/note; `409` for reusing a creation key with different input; and `429` for the normal API rate limit.

## Code examples

### Example request

```bash
curl -X GET "https://datafa.st/api/v1/mentions?websiteId=YOUR_WEBSITE_ID" \
  -H "Authorization: Bearer dft_xxx"
```

### Success response

```json
{
  "status": "success",
  "data": [
    {
      "id": "69a123456789012345678903",
      "websiteId": "65f123456789012345678901",
      "platform": "x",
      "timestamp": "2026-09-04T12:00:00.000Z",
      "text": "We launched our new website: example.com",
      "url": "https://x.com/example/status/123",
      "author": {
        "name": "Alex",
        "username": "example",
        "image": null
      },
      "engagement": {
        "likes": 12,
        "replies": 2,
        "reposts": 1,
        "quotes": 0
      },
      "media": [],
      "isRetweet": false
    }
  ],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "total": 1,
    "hasMore": false
  },
  "meta": {
    "totalMentions": 1,
    "sampled": false,
    "mentionLimit": 3,
    "timezone": "UTC",
    "startAt": "2026-08-07T00:00:00.000Z",
    "endAt": "2026-09-05T23:59:59.999Z",
    "message": "Starter includes a sample of your website's X and Reddit mentions. Upgrade to a Growth plan to unlock all available mentions: https://datafa.st/dashboard/billing",
    "upgradeUrl": "https://datafa.st/dashboard/billing"
  }
}
```