# Track Grok answers

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

Get structured output from Grok for any prompt in supported regions: the answer and the sources it cites, X/Twitter posts included

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

## Body

- `prompt` (string, required): Prompt submitted to Grok, 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.markdown` (boolean): Add a markdown version of the response to the result
  - `include.html` (boolean): A link to the answer's own public page on grok.com, in `html`, to check the answer against. No extra cost.
  - `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 the answer from Grok
- `result.html` (string): Present when include.html is true: the link to the answer's public page on grok.com.
- `result.sources` (object[]): Sources the response cites, with extra metadata
- `result.searchQueries` (string[]): Searches Grok ran to collect material for the response
- `result.model` (string): Identifier of the model that produced the response
- `result.relatedQueries` (string[]): Follow-up questions Grok suggests under its answer, in its order. Absent when it suggests none.
- `result.markdown` (string): Grok's answer rendered as Markdown (returned if include.markdown is set to 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.screenshot` (string): Present when include.screenshot is true and the answer's public page on grok.com was available: the link to its PNG screenshot.
- `result.citationPills` (object[]): Kept so every chat engine has the same shape. Grok shows no citation pills, so this is always empty; its citations are in sources.
- `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: Grok 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/grok" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Which electric car brands do people recommend?","country":"US"}'
```

TypeScript:

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

const client = new Client({ apiKey: process.env.API_KEY! });
const answer = await client.monitor.grok({
  "prompt": "Which electric car brands do people recommend?",
  "country": "US"
});
```

Python:

```python
import os
from answerline import Client

with Client(os.environ["API_KEY"]) as client:
    answer = client.monitor.grok(
        prompt="Which electric car brands do people recommend?",
        country="US",
    )
```


## Example responses

200:

```json
{
  "success": true,
  "result": {
    "text": "Drawing on a live web search, these monitors stand out for programming work...",
    "html": "https://files.answerline.dev/html/c45a5081-808d-4ed3-9c86-e4baf16c8ab8/1/page-1.html",
    "sources": [
      {
        "position": 1,
        "url": "https://techcrunch.com/programming-laptops",
        "label": "TechCrunch",
        "description": "Top monitors for coding and development",
        "preview": "A good coding laptop needs plenty of memory and a fast multi-core CPU...",
        "searchEngineText": "Best Coding Laptops of 2025",
        "siteName": "TechCrunch",
        "metadataTitle": "The Complete Coding Laptop Handbook",
        "creator": "Tech Team",
        "image": "https://techcrunch.com/preview.jpg",
        "favicon": "https://techcrunch.com/favicon.ico"
      }
    ],
    "searchQueries": [
      "coding laptop recommendations 2026",
      "leading laptops for developers 2026"
    ],
    "model": "grok-4-auto",
    "relatedQueries": [
      "Explore HubSpot AI features",
      "Compare HubSpot and Pipedrive"
    ],
    "markdown": "Drawing on a live web search, these monitors stand out for programming work...",
    "rawResponse": [
      null
    ],
    "screenshot": "https://files.answerline.dev/html/c45a5081-808d-4ed3-9c86-e4baf16c8ab8/1/3f9a1c2e8b7d4a6f9e0c1b2a3d4e5f60/page-1.png",
    "citationPills": [],
    "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"
  }
}
```