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

# Custom Search

> Search Google using your Custom Search Engine or YouRouter's default.

**Endpoint:** `GET /customsearch/v1`

Perform a Google Custom Search using the `cx` you provide. If omitted, the request uses YouRouter's default search engine.

This endpoint is useful when you need fresh web results, documentation lookup, or a programmable search engine for your own sites.

<Note>
  Search requests are covered by [Zero Completion Insurance](/features/zero-completion-insurance). Failed or empty search results are not billed as successful completions.
</Note>

<CodeGroup>
  ```python Python theme={null}
  import os
  import requests
  import json

  response = requests.get(
      "https://api.yourouter.ai/customsearch/v1",
      headers={"Authorization": f"Bearer {os.environ['YOUROUTER_API_KEY']}"},
      params={
          "q": "how to set up billing",
          "cx": "YOUR_CUSTOM_SEARCH_ENGINE_ID",
          "num": 3
      }
  )
  print(json.dumps(response.json(), indent=2))
  ```

  ```bash cURL theme={null}
  curl "https://api.yourouter.ai/customsearch/v1?q=billing&cx=YOUR_CX_ID" \
    -H "Authorization: Bearer $YOUROUTER_API_KEY"
  ```
</CodeGroup>

### Parameters

| Parameter    | Type    | Description                                                   | Required |
| ------------ | ------- | ------------------------------------------------------------- | -------- |
| `q`          | string  | The search query.                                             | Yes      |
| `cx`         | string  | Custom Search Engine ID. Uses YouRouter's default if omitted. | No       |
| `num`        | integer | Number of search results to return (1-10).                    | No       |
| `start`      | integer | The index of the first result to return.                      | No       |
| `siteSearch` | string  | Specifies a site to search.                                   | No       |

<Card title="Response Format" icon="code">
  A successful response contains an `items` array of search result objects.

  ```json theme={null}
  {
    "kind": "customsearch#search",
    "items": [
      {
        "kind": "customsearch#result",
        "title": "Billing Information - Example Docs",
        "link": "https://docs.example-app.ai/billing"
      }
    ]
  }
  ```
</Card>

## Typical Use Cases

<AccordionGroup>
  <Accordion title="Q&A over your own docs">
    Create a Google Programmable Search Engine that indexes only your documentation domains, then pass the top results into a model to answer product questions with fresher grounding.
  </Accordion>

  <Accordion title="Real-time web retrieval">
    Use search results to fetch recent articles, pages, or announcements before asking a model to summarize or reason over them.
  </Accordion>
</AccordionGroup>