> For the complete documentation index, see [llms.txt](https://docs.pullbay.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pullbay.com/api-reference/endpoints/google-search.md).

# Google Search

Google Search: web search results. A single read-only `GET` endpoint that returns organic Google search results for a query.

**Base URL:** `https://dashboard.pullbay.com/api`

## Endpoints

| Endpoint                    | Description               | Pagination      |
| --------------------------- | ------------------------- | --------------- |
| `GET /google-search/search` | Search the web via Google | Page / maxItems |

***

### Search

Returns Google search results for `query`.

**Request**

```bash
GET /google-search/search
Authorization: Bearer YOUR_API_KEY
```

**Parameters**

| Parameter  | Type    | Required | Description                                                       |
| ---------- | ------- | -------- | ----------------------------------------------------------------- |
| `query`    | string  | Yes      | Search query, 1–1000 characters                                   |
| `safe`     | string  | No       | SafeSearch filter level                                           |
| `hl`       | string  | No       | Interface/results language code (e.g. `en`)                       |
| `country`  | string  | No       | 2-letter ISO country code for the search region                   |
| `count`    | string  | No       | Results per page; only `10` is supported                          |
| `noEncode` | string  | No       | Skip URL-encoding the query before sending it upstream            |
| `page`     | integer | No       | Page number, 1+. Mutually exclusive with `maxItems`               |
| `maxItems` | integer | No       | One-shot bulk pull, 1–200 results. Mutually exclusive with `page` |

**Example**

```bash
curl -G "https://dashboard.pullbay.com/api/google-search/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d query="openai" \
  -d country=us \
  -d hl=en \
  -d page=1
```

**Response**

```json
{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "type": "searchResult",
      "title": "OpenAI | OpenAI",
      "link": "https://openai.com/",
      "snippet": "We believe our research will eventually lead to artificial general intelligence, a system that can solve human-level problems."
    }
  ],
  "pagination": { "page": 1, "hasNextPage": true, "cursor": null, "offset": null },
  "pricing": { "creditsCharged": 1 }
}
```

**Credit cost:** dynamic, returned in `pricing.creditsCharged`. Using `maxItems` to pull more results in one call costs proportionally more than a single page.

***

## Object schemas

### GoogleSearchResult object

| Field     | Type   | Description                                    |
| --------- | ------ | ---------------------------------------------- |
| `type`    | string | Result type, always `searchResult`             |
| `title`   | string | Page title as shown in search results          |
| `link`    | string | URL of the result                              |
| `snippet` | string | Descriptive text excerpt shown under the title |

***

## Errors

All non-2xx responses share the same envelope:

```json
{
  "status": 400,
  "message": "Bad request",
  "success": false,
  "error": { "code": "BAD_REQUEST" }
}
```

| Status | Meaning                                  |
| ------ | ---------------------------------------- |
| `400`  | Bad request — missing/invalid parameters |
| `402`  | Insufficient credits                     |
| `404`  | App, developer, or review set not found  |

## Pagination and Bulk Pulls

* Use `page` to walk through results one page at a time (`count=10` results per page); `pagination.hasNextPage` in the response tells you whether to keep going.
* Use `maxItems` instead of `page` to pull a larger result set in a single call (up to 200 results). Don't pass both — they're mutually exclusive.
* `count` currently only accepts the value `10` and can typically be omitted.

## Language and Region Codes

* `hl` accepts a 2–3 letter ISO 639 language code (`en`, `es`, `ja`, ...) to control the language of result snippets and UI strings.
* `country` accepts a 2-letter ISO 3166-1 alpha-2 code (`us`, `gb`, `jp`, ...) to bias results to a search region.
* If omitted, both default to a US/English search context.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.pullbay.com/api-reference/endpoints/google-search.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.