# AlsoAsked

> AlsoAsked surfaces the questions people ask Google ("People Also Ask") for any search term, language and region. This file is a self-contained reference for integrating with the public **AlsoAsked API** programmatically.

This document gives AI agents and developers everything needed to make correct requests to AlsoAsked. If you are writing code or making requests on a user's behalf, use the public API described here.

## Which endpoint to use

AlsoAsked runs on two separate domains. Choose the right one:

- **`https://alsoaskedapi.com`** - the public API. Versioned under `/v1`, authenticated with API keys, documented and stable. **Use this for all programmatic access.**
- **`https://sandbox.alsoaskedapi.com`** - the sandbox public API. Same shape as live, free to use, returns placeholder results for development and testing.
- **`https://alsoasked.com`** - the marketing website and web app for human visitors. Paths under `https://alsoasked.com/api/*` (for example `https://alsoasked.com/api/v1/search`) are the website's **internal** backend. They authenticate using browser session cookies and CSRF tokens, are undocumented, may change at any time, and reject API keys. **Do not call `https://alsoasked.com/api/*` from integrations, scripts or agents.** If an example or tool points you there, switch the host to `https://alsoaskedapi.com` and use the `/v1` paths below.

## Base URLs

- Live: `https://alsoaskedapi.com/v1`
- Sandbox: `https://sandbox.alsoaskedapi.com/v1`

## Authentication

Every request must include an API key in the `X-Api-Key` header:

```
X-Api-Key: aa-live-xxxxxxxxxxxxxxxxxxxxxxxx
```

- Create and manage keys under Developers → API keys at https://alsoasked.com/developer/keys (maximum 10 keys).
- Live keys are prefixed `aa-live-`; sandbox keys are prefixed `aa-sandbox-`. Use a live key against `alsoaskedapi.com` and a sandbox key against `sandbox.alsoaskedapi.com`.
- A **Pro subscription** is required to use the live API. The sandbox is free.
- Requests without a valid API key are rejected. There is no session-cookie or OAuth flow for the public API.

## Credits

Searches are paid for with credits: a depth `2` search costs 1 credit and a depth `3` search costs 4 credits (cached results returned with `fresh: false` are not charged). Each plan includes a monthly credit allowance.

Pro accounts can also buy **pay-as-you-go credits**, which are spent alongside your plan's credits to pay for searches. They let API usage continue once the monthly allowance is exhausted, without upgrading plan tier. They can be purchased manually, or set up to top up automatically: enable automatic top-ups to be charged for a chosen number of credits whenever your balance falls below a threshold. Check your remaining balance with `GET /account`, and purchase or manage credits at https://alsoasked.com/credits.

## Endpoints

### GET /account

Returns the authenticated account's details, including the number of remaining credits.

```sh
curl https://alsoaskedapi.com/v1/account \
  -H "X-Api-Key: aa-live-xxxxxxxxxxxxxxxxxxxxxxxx"
```

### GET /search

Returns a paginated list of past searches, newest first.

- Query parameters: `count` (page size) and `page` (1-based page number).

```sh
curl "https://alsoaskedapi.com/v1/search?count=20&page=1" \
  -H "X-Api-Key: aa-live-xxxxxxxxxxxxxxxxxxxxxxxx"
```

### POST /search

Performs a search. By default the request is synchronous and waits for results (up to a 90-second timeout); set `async: true` to return immediately and receive updates via webhooks (or poll `GET /search/{searchId}`).

Request body (JSON):

| Field | Type | Default | Notes |
| --- | --- | --- | --- |
| `terms` | string[] | - | Required. 1–1000 unique terms; each 1–4127 characters. |
| `language` | string | `en` | Language code supported by AlsoAsked. |
| `region` | string | `us` | Two-letter ISO 3166-1 region code. |
| `depth` | integer | `2` | `2` or `3`. Depth `2` costs 1 credit; depth `3` costs 4 credits. |
| `fresh` | boolean | `false` | `false` returns cached results when available (no credit charged); `true` always performs a fresh search (charges a credit). |
| `async` | boolean | `false` | `false` waits for results (max 90s); `true` returns immediately with an ID. |
| `notify_webhooks` | boolean | `true` | Whether to notify configured webhooks when the search status changes. |
| `latitude` | number | - | Optional, -90 to 90, for location-specific searches. |
| `longitude` | number | - | Optional, -180 to 180, for location-specific searches. |

```sh
curl -X POST https://alsoaskedapi.com/v1/search \
  -H "X-Api-Key: aa-live-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "terms": ["how to grow broad beans"],
    "language": "en",
    "region": "gb",
    "depth": 2,
    "async": false
  }'
```

The response follows the Search Request Results schema, including an `id` (32-character identifier), `language`, `region`, `status`, and the question results when complete. If a synchronous search exceeds 90 seconds, the response returns the `id` and status with empty results; fetch the results later with `GET /search/{searchId}`.

### GET /search/{searchId}

Returns the details and results for a previously created search, identified by its `id`.

```sh
curl https://alsoaskedapi.com/v1/search/9J1VrsN0ku2E6xW8M5Xh3zylpfZgIcba \
  -H "X-Api-Key: aa-live-xxxxxxxxxxxxxxxxxxxxxxxx"
```

### DELETE /search/{searchId}

Deletes a search: clears its cached results and masks the term in your search history. Returns `204 No Content`.

```sh
curl -X DELETE https://alsoaskedapi.com/v1/search/9J1VrsN0ku2E6xW8M5Xh3zylpfZgIcba \
  -H "X-Api-Key: aa-live-xxxxxxxxxxxxxxxxxxxxxxxx"
```

## Rate limiting

- 100 requests per rolling 5-minute window (sliding window counter), enforced per API key **and** per IP address.
- Exceeding the limit returns `429 Too Many Requests`.
- Response headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` (Unix time). When limited, a `Retry-After` header (seconds) is also returned.

## Webhooks (asynchronous searches)

Register endpoints under Developers → Webhooks at https://alsoasked.com/developer/webhooks (maximum 5). Webhooks notify your server when a search's status changes, so you don't need to poll.

- Events: `search_created`, `search_started`, `search_succeeded`, `search_failed`.
- The request body is a JSON Search Request Results object; `Content-Type` is `application/json` and the User-Agent is `AlsoAsked/1.0`.
- Headers include `X-AlsoAsked-Webhook-Event`, `X-AlsoAsked-Environment` (`live` or `sandbox`), `X-AlsoAsked-Timestamp` (UTC epoch seconds), `X-AlsoAsked-Credits`, `X-AlsoAsked-Api-Version`, and `X-AlsoAsked-Signature`.
- Verify authenticity with `X-AlsoAsked-Signature`: the hex-encoded `HMAC-SHA384` hash of the raw request body, a `.`, and the `X-AlsoAsked-Timestamp` value (in that order), computed with your webhook signing key - i.e. `hex(HMAC-SHA384(signingKey, rawRequestBody + "." + timestamp))`.
- Endpoint URLs must be public HTTPS/HTTP, must not include an explicit port (the scheme default of 80 or 443 is used), must not be localhost or a raw IP, and must not redirect.

## Further reading

- Documentation and guides: https://developers.alsoasked.com
- OpenAPI 3.1 specification: https://github.com/AlsoAsked/also-asked-api-specification/blob/main/openapi/openapi.yaml
- Pricing and credits: https://alsoasked.com/pricing
- Support: https://help.alsoasked.com (help@alsoasked.com)
- Terms of service: https://alsoasked.com/eula