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

# Citation pills

> Schema for inline citation pills returned by the ChatGPT endpoint, with each cited source attached to the visible pill chip it appears on in the answer.

This section documents the **citationPills** data returned by the [ChatGPT endpoint](/api-reference/endpoint/monitor-chatgpt). Citation pills are part of the ChatGPT response — no separate API call is needed.

## Example request

```json theme={null}
{
  "prompt": "What is the best AI software?",
  "model": "CHATGPT",
  "country": "US"
}
```

This produces a response containing the `citationPills` array documented below.

## Overview

ChatGPT cites sources inline as it answers; the `result.citationPills` array exposes those citations denormalized: each entry is one **(pill, source)** pair carrying a per-source `label` (the source's own page title from the citation event), a `citationPillId` that groups entries from the same chip, and the per-source `url`/`domain`/`description`/`position`, plus the ChatGPT-only `type` and `datePublished` fields.

When a chip cites N sources, the array contains N entries sharing the same `citationPillId` but carrying different per-source `label`, `url`, and `domain`. Group by `citationPillId` to recover the pill-level structure.

The `markdown` field contains these citations as inline `[label](url)` links; the `text` field contains plain text without the links. The `citationPills` array provides structured metadata about all inline citations.

The field is omitted from `result` when the answer has no pills.

## Citation pill structure

Each citation pill contains:

| Field            | Type             | Description                                                                                                                                                                                                                               |
| ---------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `label`          | string           | Per-source title of the citation. Always present; may be an empty string when the citation event ships no title — read `domain` / `url` for source identity in that case.                                                                 |
| `citationPillId` | integer          | 0-based identifier shared by all entries from the same chip. **Note:** unlike the other providers (Google AIO, AI Mode, Copilot, Perplexity, Gemini) which use 1-based `citationPillId`, ChatGPT's IDs start at 0 for historical reasons. |
| `url`            | string           | The URL of the citation source                                                                                                                                                                                                            |
| `domain`         | string           | Domain of the citation source (e.g., `"example.com"`)                                                                                                                                                                                     |
| `description`    | string, optional | Description of the citation content. **The key is omitted when ChatGPT provides no snippet** — see `type`.                                                                                                                                |
| `position`       | integer          | 1-based position of this source in the sibling [`result.sources`](/api-reference/endpoint/chatgpt/sources) array.                                                                                                                         |
| `type`           | string           | *ChatGPT-only.* Discriminator: `"searchResult"` or `"groupedWebpage"`. See below for what this signals about `description`.                                                                                                               |
| `datePublished`  | string, optional | *ChatGPT-only.* ISO 8601 date string of when the source was published. Omitted when the citation event ships no publish date — never emitted as `null`.                                                                                   |

### `type` values

`type` reflects the structure of the underlying citation event in ChatGPT's response:

* **`"searchResult"`** — a regular web search hit. ChatGPT provides a snippet, so `description` is populated.
* **`"groupedWebpage"`** — a citation rendered in the ChatGPT UI as a multi-source card (commonly used for community references like Reddit, Wikipedia, and ArXiv). ChatGPT does not provide a per-source snippet for these, so **the `description` key is omitted entirely from the pill object**.

When the same source URL appears as both a search result and inside a grouped card, the search-result form (with description) is preferred.

## Response example

```json theme={null}
{
  "success": true,
  "result": {
    "text": "**ChatGPT** — Most versatile for writing, reasoning, and general problem-solving.\n**Claude** — Strong focus on safety and ethical reasoning.",
    "markdown": "**ChatGPT** — Most versatile for writing, reasoning, and general problem-solving. [Top 10 Best AI Apps in 2025](https://www.top10.com/best-lists/best-ai-apps)\n**Claude** — Strong focus on safety and ethical reasoning. [Best AI Platforms Compared](https://www.godofprompt.ai/blog/best-ai)",
    "citationPills": [
      {
        "label": "Top 10 Best AI Apps in 2025",
        "citationPillId": 0,
        "url": "https://www.top10.com/best-lists/best-ai-apps",
        "domain": "top10.com",
        "description": "A guide to AI applications available today",
        "position": 1,
        "type": "searchResult",
        "datePublished": "2025-01-15"
      },
      {
        "label": "Artificial intelligence — Wikipedia",
        "citationPillId": 1,
        "url": "https://en.wikipedia.org/wiki/Artificial_intelligence",
        "domain": "en.wikipedia.org",
        "position": 2,
        "type": "groupedWebpage"
      }
    ]
  }
}
```