# Google Videos

`POST https://api.serpkite.com/v1/videos` · Credits: 1 per page

Video results with channel, duration, date and thumbnail.

Google Videos results with channel, duration, publish date and thumbnail.

## Request body

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `q` **required** | string |  | The search query. Required. Up to 2,048 characters. |
| `country` | string | `us` | Country to search from, as a two-letter ISO code (us, gb, de, in…). |
| `language` | string | `en` | Interface language, as a language code (en, de, fr, pt-BR…). |
| `num` | integer | `10` | Results per call. 10 per page; 100 fetches the top 100 as a depth bundle for 7 credits instead of 10. One of: `10`, `20`, `30`, `50`, `100`. |
| `page` | integer | `1` | Results page, 1–10. Each page is billed separately. |
| `time` | string |  | Restrict to recent results. Shorthand for tbs=qdr:*. One of: `hour`, `day`, `week`, `month`, `year`. |
| `tbs` | string |  | Raw Google tbs filter, e.g. qdr:w or cdr:1,cd_min:… |
| `format` | string | `json` | Response format. markdown is LLM-ready prose; compact is JSON with only the fields agents need. One of: `json`, `compact`, `markdown`. |
| `fields` | string |  | Comma-separated projection, e.g. results.title,results.link,knowledge_graph. Cuts tokens. |
| `max_age` | integer |  | Accept a cached result up to this many seconds old. Cache hits cost 50% of the credits. |
| `engine` | string or array | `google` | Which search providers may answer. google is Google only (SerpKite still fails over across its own proxy pools); auto falls back to other providers when Google is blocked or times out; consensus (search only) asks several independent indexes in parallel, merges the results by URL, ranks them by agreement and lists each result's sources, at the sum of one page per provider that returned results; a provider name or a list (e.g. google,brave) restricts the request to those. meta.engine names the provider that answered. One of: `google`, `auto`, `consensus`, `brave`, `bing`, `yahoo`, `duckduckgo`, `mojeek`, `wikipedia`. |

## Example request

cURL:

```bash
curl https://api.serpkite.com/v1/videos \
  -H "Authorization: Bearer $SERPKITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q":"how to pull an espresso shot","country":"us"}'
```

TypeScript:

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

const sk = new SerpKite(); // reads SERPKITE_API_KEY
const res = await sk.videos({ q: "how to pull an espresso shot", country: "us" });
console.log(res.results[0].title, res.meta.credits_used);
```

Python:

```python
from serpkite import SerpKite

sk = SerpKite()  # reads SERPKITE_API_KEY
res = sk.videos("how to pull an espresso shot", country="us")
print(res.results[0].title, res.meta.credits_used)
```

## Response fields

| Field | Type | Description |
| --- | --- | --- |
| `request` | object | The normalised request, with defaults filled in: `endpoint`, `engine`, `q`, `country`, `language`, `location`, `num`, `page`, `device`, `autocorrect`… |
| `results[]` | array | `position`, `title`, `link`, `domain`, `snippet`, `image_url`, `duration`, `source`, `channel`, `date`. |
| `meta` | object | `request_id`, `credits_used`, `cached`, `cached_at`, `engine` (the provider that answered), `route` (provider attempts, see [Search providers](https://serpkite.com/docs/providers)), `latency_ms`, `parse_quality` (`ok`, `partial`, `empty`), `resolved_urls`. |

## Example response

```json
{
  "request": {
    "endpoint": "videos",
    "engine": "google",
    "q": "how to pull an espresso shot",
    "country": "us",
    "language": "en"
  },
  "results": [
    {
      "position": 1,
      "title": "How to pull the perfect espresso shot",
      "link": "https://video.example.com/watch?v=abc123",
      "domain": "video.example.com",
      "snippet": "Dose, grind, tamp and time: a step-by-step guide…",
      "image_url": "https://video.example.com/thumb/abc123.jpg",
      "duration": "8:42",
      "source": "Example Video",
      "channel": "Home Barista Lab",
      "date": "Mar 3, 2026"
    }
  ],
  "meta": {
    "request_id": "req_01J8ZK4M6Q2V7",
    "credits_used": 1,
    "cached": false,
    "engine": "google",
    "latency_ms": 1034,
    "parse_quality": "ok",
    "resolved_urls": true
  }
}
```

## 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. |

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

## Related

- [Search](https://serpkite.com/docs/endpoints/search)