# Gemini

`POST https://api.serpkite.com/v1/gemini` · Credits: 3 per answer (the same in a batch); failed, refused and empty answers are free

Ask Google Gemini as a logged-out user and get its answer as text and Markdown, with the sources it grounded on and the model it reports.

Opens gemini.google.com as a logged-out visitor in a standard browser and sends `prompt`. When Gemini grounds its answer in Google Search, the pages it used come back in `sources` and the `[n](link)` citations in `markdown` point at them. `model` is the model Gemini reports to guests.

**Billing:** 3 credits per answer, 1.5 from the cache with `max_age`. AI answers cost the same in [`POST /v1/batches`](https://serpkite.com/docs/batch): the batch lane does not halve them. A failed, refused or empty answer is refunded (`503`, nothing billed).

**Latency:** answers typically take 5–30 s; requests wait up to 90 s. Set a client timeout of at least 120 s, or queue prompts with [batches](https://serpkite.com/docs/batch) or a [monitor](https://serpkite.com/docs/endpoints/monitors) instead of holding requests open.

**Variance:** assistants answer the same prompt differently from run to run and by country. To measure visibility, ask each prompt several times and compare shares, not single answers. See [AI visibility tracking](https://serpkite.com/docs/guides/ai-visibility-tracking).

## Request body

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `prompt` **required** | string |  | The message to the assistant, up to 4,000 characters. Required. (`q` is not accepted here.) |
| `country` | string |  | Ask as a visitor in this country (ISO 3166-1 alpha-2): the answer follows the visitor's location. |
| `language` | string | `en` | Interface language (e.g. `en`, `de`). The answer follows the prompt's language. |
| `track` | string[] |  | Up to 20 brands (`"Acme"`) or domains (`"acme.com"`, subdomains match), 100 characters each, to check the answer for. Each comes back in `mentions`. A term with a dot is a domain: it matches sources and product links on that domain; other terms match whole words, case-insensitively. |
| `include_html` | boolean | `false` | Also return the answer's HTML in `html`. |
| `format` | string | `json` | `markdown` returns the answer, its sources, searches, products and a Mentions section as one Markdown document; `compact` keeps `text`, `sources` (`n`, `title`, `link`), `search_queries`, `products` and `places`. One of: `json`, `markdown`, `compact`. |
| `fields` | string |  | Comma-separated projection, e.g. results.title,results.link,knowledge_graph. Cuts tokens. |
| `max_age` | integer |  | Accept a cached answer up to this many seconds old, at half price. Answers are cached for at most 1 hour, and only a request with `max_age` reads the cache. |

## Example request

cURL:

```bash
curl https://api.serpkite.com/v1/gemini \
  -H "Authorization: Bearer $SERPKITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"How do heat pumps work in cold climates?"}'
```

TypeScript:

```ts
import { SerpKite } from "serpkite";

const sk = new SerpKite(); // reads SERPKITE_API_KEY
const res = await sk.gemini({ prompt: "How do heat pumps work in cold climates?" });
console.log(res.markdown, res.sources.length);
```

Python:

```python
from serpkite import SerpKite

sk = SerpKite()  # reads SERPKITE_API_KEY
res = sk.gemini(prompt="How do heat pumps work in cold climates?")
print(res.markdown, len(res.sources))
```

## Response fields

| Field | Type | Description |
| --- | --- | --- |
| `request` | object | The normalised request: `endpoint`, `prompt`, `country`, `language` (not chatgpt), `web_search` (chatgpt), `include_html`. |
| `text` | string | The answer as plain text. |
| `markdown` | string | The answer as Markdown. Citations are `[n](link)`, where `n` is the `position` of a source in `sources`. |
| `html` | string | The answer's HTML, only with `include_html: true`. |
| `model` | string | The model the assistant reports to logged-out visitors, when it reports one. |
| `sources[]` | array | `position` (the `n` in the citations), `title`, `link`, `domain`, `snippet`, `date`, `cited` (`true`: cited inline in the answer; `false`: only listed beside it). |
| `search_queries[]` | array | The searches the assistant ran to answer (its fan-out), where it shows them. |
| `products[]` | array | Product cards shown with the answer: `position`, `title`, `brand`, `price` (as shown), `extracted_price`, `currency` (ISO 4217 when unambiguous), `rating`, `reviews`, `merchant`, `link`, `image`, `description`. |
| `places[]` | array | Local businesses the answer showed, same shape as [/v1/maps](https://serpkite.com/docs/endpoints/maps) results. |
| `related_questions[]` | array | Follow-up questions the assistant suggested. |
| `mentions[]` | array | Only with `track`, one per term: `term`, `mentioned` (the answer text names it), `cited` (a cited source matches it), `sources` (positions of matching sources, cited or listed), `products` (positions of matching products), `text_position` (where the text first names it, 0 = start to 1 = end; -1 when it doesn't). See [AI visibility tracking](https://serpkite.com/docs/guides/ai-visibility-tracking). |
| `meta` | object | `request_id`, `credits_used`, `cached`, `cached_at`, `engine` (the assistant), `latency_ms`, `parse_quality`. |

## Example response

```json
{
  "request": {
    "endpoint": "gemini",
    "prompt": "How do heat pumps work in cold climates?",
    "country": "us",
    "language": "en"
  },
  "text": "Cold-climate heat pumps keep heating well below freezing because they use variable-speed compressors and refrigerants that still absorb heat from outdoor air at -15 °C or lower…",
  "markdown": "Cold-climate heat pumps keep heating well below freezing because they use **variable-speed compressors** and refrigerants that still absorb heat from outdoor air at -15 °C or lower [1](https://www.example.gov/heat-pumps-cold-climates)…",
  "model": "3.5 Flash-Lite",
  "sources": [
    {
      "position": 1,
      "title": "Heat pumps in cold climates",
      "link": "https://www.example.gov/heat-pumps-cold-climates",
      "domain": "example.gov",
      "cited": true
    }
  ],
  "search_queries": [],
  "products": [],
  "meta": {
    "request_id": "req_01J8ZK4M6Q2V7",
    "credits_used": 5,
    "cached": false,
    "engine": "gemini",
    "latency_ms": 61200,
    "parse_quality": "ok"
  }
}
```

## Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `invalid_request` | A parameter is missing or invalid. |
| 401 | `unauthorized` | The API key is missing, invalid or revoked. |
| 402 | `insufficient_credits` | Your balance is too low. Buy a pack or wait for the monthly free grant. |
| 429 | `rate_limited` | Too many requests per second for your plan. Retry after the Retry-After header. |
| 503 | `upstream_error` | Google could not be fetched or parsed. Not billed; retry after Retry-After. |
| 503 | `upstream_blocked` | Google is rate limiting the upstream right now, or refused this query (Retry-After 120 s; rephrase it, or use engine=auto where another engine serves the endpoint). Not billed; retry after Retry-After. |
| 503 | `upstream_timeout` | The search took too long. Not billed; retry after Retry-After. |

All errors: https://serpkite.com/docs/errors

## Notes

- Most answers take 5–30 s (about 12 s at the median); answers that search the web take longer.
- We ask like a logged-out visitor in a standard browser and never sign in. When the assistant refuses the visit or asks the visitor to sign in, the call fails with `503 upstream_blocked` and is free. See [AI assistants](https://serpkite.com/docs/ai-assistants).
- `engine` is not accepted (the path names the assistant), and neither are search options such as `q`, `num` or `location`: they return `400 invalid_request`.
- Monitors take `endpoint: "gemini"` with `prompt` and `track`, and report every run's answer with `new_sources` and `mentions`. See [Monitors](https://serpkite.com/docs/endpoints/monitors).
- The remote MCP server has a `gemini` tool. See [MCP server](https://serpkite.com/docs/mcp).
- The prompt is handled like a search query: never logged, and cached for at most an hour under a hashed key. See [Privacy and data retention](https://serpkite.com/docs/privacy-and-data-retention).

## Related

- [AI assistants overview](https://serpkite.com/docs/ai-assistants)
- [AI visibility tracking guide](https://serpkite.com/docs/guides/ai-visibility-tracking)
- [ChatGPT](https://serpkite.com/docs/endpoints/chatgpt)
- [Copilot Search](https://serpkite.com/docs/endpoints/copilot)
- [Google AI Mode](https://serpkite.com/docs/endpoints/ai_mode)
- [Brave AI](https://serpkite.com/docs/endpoints/brave_ai)