# Track Copilot answers

`POST https://api.answerline.dev/v1/monitor/copilot`

Get structured output from Copilot on your brand, your products or any other topic, in many regions

From $2.74 per 1,000 requests. Failed requests are free. Also runs as an async task of type `COPILOT`.

## Body

- `prompt` (string, required): Prompt submitted to Copilot, up to 2,000 characters. A longer prompt is refused with a 400 that states its length.
- `country` (string, required): Code of the country or region used to localize the response
- `include` (object): Flags that add extra output formats to the response (optional)
  - `include.html` (boolean): Not available on Copilot: its answer is read without a page to copy. `true` is refused with a 400 before anything runs, uncharged; `false` is accepted and changes nothing.
  - `include.markdown` (boolean): Add a markdown version of the response to the result
  - `include.rawResponse` (boolean): Return the answer as normalized stream events. For the engine's answer as received, use `include.rawWire`.
  - `include.rawWire` (boolean): Return the engine's own response as received in result.rawWire: the answer stream, the rendered results pages or the RSS feed, without Gemini's detected location or ChatGPT's session tokens; null where it was not captured. Free. See https://answerline.dev/docs/output-formats#raw-wire
  - `include.screenshot` (boolean): Return a full-page PNG screenshot of the engine's page as it showed the finished answer, in result.screenshot: a link, or one link per results page on Google Search. On ChatGPT, Gemini, AI Mode, Google Search, Perplexity and Grok; other engines refuse it with a 400. Absent when the answer was read without a rendered page or its page was not available. Free. See https://answerline.dev/docs/output-formats#screenshots
- `state` (string): US state code (e.g. "CA", "DC" included). Sent without a country, the request asks for the US; sent with any country other than "US", it is refused with a 400, uncharged. ChatGPT and Gemini answer as a person in that state sees it; every other engine accepts it and answers for the whole US, at the price of a request without it. provenance.requestedState reports the state asked. See https://answerline.dev/docs/coverage#states
- `answerDepth` ("any" | "full" | "quick"): Accepted so existing requests stay valid; it does not change the answer or the price. Every engine writes one depth: Perplexity answers every request with its Quick Search answer, and provenance.answerDepth says quick. See https://answerline.dev/docs/engine-features/#answer-depth

## Returns

- `result.text` (string): Text of Copilot's reply
- `result.html` (string): Never present: include.html is refused for Copilot.
- `result.sources` (object[]): Sources the response cites
- `result.citationPills` (object[]): Citation pills that appear inline in the Copilot answer. Every element pairs one pill with one source: a pill backed by N sources (a chip made from consecutive citation events) yields N elements with the same `citationPillId`, each holding that source's own `label`, `url` and `domain`. Grouping by `citationPillId` rebuilds the pills. Empty when the answer has no pills.
- `result.shoppingCards` (object[]): Shopping/product cards parsed from the response (if any)
- `result.map` (object[]): Map entries for businesses or places parsed from the response (if any)
- `result.searchQueries` (string[]): Query fan-out: the web searches Copilot performed as it wrote the response. Returned automatically whenever there is at least one, at no extra cost.
- `result.markdown` (string): Copilot's reply as Markdown; returned only if include.markdown is true
- `result.rawResponse` (object[]): The answer as normalized stream events (present when include.rawResponse is true). For the engine's answer as received, use include.rawWire.
- `result.links` (object[]): The links in the answer's text, in the order a reader meets them: one entry per web (http or https) link the answer shows, images and code aside, with the words it shows (text), where it goes (url), its domain and its 1-based position. Sources cited by pills are in citationPills; links to the same page appear in both when the answer does both. Empty when the text links nowhere.

## Responses

- 200: Copilot monitoring result (success)
- 400: Bad Request - the request failed validation
- 401: Unauthorized - authentication failed
- 403: Forbidden - INSUFFICIENT_CREDITS: the balance does not cover this request
- 404: Not Found - No such route, or the engine is paused
- 409: Conflict - the resource is in a conflicting state
- 429: Too Many Requests - the call could not start now (`CONCURRENT_LIMIT_EXCEEDED`), or the service dropped the request because it was overloaded (`SERVICE_OVERLOADED`); that case returns `Retry-After` without any limit headers. `RATE_LIMIT_EXCEEDED`, with `Retry-After`, is sent only when one address presented too many unknown keys
- 499: Client Closed Request - the client cancelled the request
- 500: Internal Server Error
- 502: Bad Gateway - the engine failed

## Request

curl:

```bash
curl -X POST "https://api.answerline.dev/v1/monitor/copilot" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Cheapest way to send money abroad","country":"US"}'
```

TypeScript:

```ts
import { Client } from "@answerline/sdk";

const client = new Client({ apiKey: process.env.API_KEY! });
const answer = await client.monitor.copilot({
  "prompt": "Cheapest way to send money abroad",
  "country": "US"
});
```

Python:

```python
import os
from answerline import Client

with Client(os.environ["API_KEY"]) as client:
    answer = client.monitor.copilot(
        prompt="Cheapest way to send money abroad",
        country="US",
    )
```


## Example responses

200:

```json
{
  "success": true,
  "result": {
    "text": "Happy to help you pick a monitor that works well for coding...",
    "html": "https://files.answerline.dev/html/c45a5081-808d-4ed3-9c86-e4baf16c8ab8/1/page-1.html",
    "sources": [
      {
        "position": 1,
        "url": "https://docs.microsoft.com/",
        "label": "Microsoft Docs",
        "description": "Official developer docs"
      }
    ],
    "citationPills": [
      {
        "label": "Vendor Help Center",
        "citationPillId": 1,
        "url": "https://docs.microsoft.com/",
        "domain": "docs.microsoft.com",
        "description": "Official developer docs",
        "position": 1
      },
      {
        "label": "Neovim source on GitHub",
        "citationPillId": 1,
        "url": "https://github.com/microsoft/vscode",
        "domain": "github.com",
        "description": "Neovim repository",
        "position": 2
      }
    ],
    "shoppingCards": [
      {
        "type": "shoppingProducts",
        "layout": "Carousel",
        "products": [
          {
            "product": {
              "id": "string",
              "groupId": "string",
              "brandGroupId": "string"
            },
            "position": 1,
            "offerId": "string",
            "url": "string",
            "name": "string",
            "description": "string",
            "images": [
              {
                "title": null,
                "url": null
              }
            ],
            "specifications": [
              {
                "displayName": null,
                "values": []
              }
            ],
            "tags": [
              "string"
            ],
            "price": {
              "amount": 0,
              "currency": "string",
              "currencySymbol": "string"
            },
            "seller": "string",
            "sellerLogoUrl": "string",
            "brandName": "string",
            "rating": {
              "value": 0,
              "count": 0
            },
            "canTrackPrice": false
          }
        ]
      }
    ],
    "map": [
      {
        "name": "Lakeside Science Museum",
        "position": 1,
        "placeId": "ChIJEYpTsk__W4gR2sQLGzOjE3o",
        "location": {
          "address": "250 Harbor Dr, Duluth, MN 55802",
          "latitude": 35.823257,
          "longitude": -83.5787498
        },
        "phoneNumber": "(865) 868-1800",
        "url": "http://www.wonderworksonline.com/pigeon-forge/",
        "reviews": [
          {
            "count": 10625,
            "rating": 4.3,
            "providerName": "Google",
            "providerIconUrl": null,
            "url": "https://maps.google.com/?cid=8796553937077126362"
          }
        ],
        "photos": [
          {
            "url": "https://lh3.googleusercontent.com/gps-cs-s/example",
            "altText": null,
            "providerName": null,
            "providerUrl": "https://maps.google.com"
          }
        ],
        "openState": "Open · Closes 8 PM",
        "category": "Amusement park",
        "price": null,
        "layerLabel": "Theme Parks"
      }
    ],
    "searchQueries": [
      "coding laptop recommendations 2025",
      "laptop reviews for programmers"
    ],
    "markdown": "Happy to help you pick a monitor that works well for coding...",
    "rawResponse": [
      null
    ],
    "links": [
      {
        "position": 1,
        "text": "Nike Pegasus 42",
        "url": "https://www.nike.com/t/pegasus-42-mens-road-running-shoes",
        "domain": "nike.com"
      }
    ]
  }
}
```

400:

```json
{
  "success": false,
  "error": "Request validation failed",
  "details": [
    {
      "field": "prompt",
      "message": "Prompt must not be empty"
    }
  ]
}
```

502:

```json
{
  "error": {
    "code": "EXTERNAL_SERVICE_ERROR",
    "message": "External service error: the service failed",
    "details": {
      "service": "CHATGPT"
    },
    "timestamp": "2025-01-15T12:00:00.000Z"
  }
}
```