# Search Domains

> Look up a name across .com, .net and .org and get ideas.

Requires an API key with the `read` scope.

Checks the exact name on `.com`, `.net` and `.org` (a TLD you type is checked first) and adds related ideas. Results are cached for ten minutes.

## Query Parameters

<ParamField query="q" type="string" required>
  A name such as `yourbrand` or `yourbrand.com`. A pasted URL is reduced to its name. Up to 253 characters.
</ParamField>

<ParamField query="exclude" type="string">
  Comma-separated domains to leave out of the results, for example ones already in your order. Up to 4,000 characters.
</ParamField>

## Response

<ResponseField name="data" type="object">
  Results.

  <Expandable title="data">
    <ResponseField name="query" type="string">What you typed.</ResponseField>
    <ResponseField name="label" type="string">The name that was searched.</ResponseField>
    <ResponseField name="exact" type="array">
      The name on each TLD checked.

      <Expandable title="exact">
        <ResponseField name="domain" type="string">Full domain.</ResponseField>
        <ResponseField name="inOrder" type="boolean">Whether it is in `exclude`.</ResponseField>
        <ResponseField name="available" type="boolean">Whether it can be registered.</ResponseField>
        <ResponseField name="banned" type="boolean">Whether the registrar refuses it.</ResponseField>
        <ResponseField name="priceCents" type="integer">Registration price in US cents, or `null`.</ResponseField>
        <ResponseField name="renewalPriceCents" type="integer">Renewal price in US cents, or `null`.</ResponseField>
      </Expandable>
    </ResponseField>
    <ResponseField name="suggestions" type="array">
      Up to 10 related domains.

      <Expandable title="suggestions">
        <ResponseField name="domain" type="string">Full domain.</ResponseField>
        <ResponseField name="priceCents" type="integer">Registration price in US cents.</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
```bash cURL
curl -X GET "https://api.foxreach.io/api/v1/managed-inboxes/domains/search?q=yourbrand" \
  -H "X-API-Key: otr_your_key"
```

```python Python SDK (beta)
from foxreach import FoxReach

client = FoxReach(api_key="otr_your_key")
results = client.managed_inboxes.search_domains("yourbrand")
```

```typescript TypeScript SDK (beta)
import { FoxReach } from "foxreach";

const client = new FoxReach({ apiKey: "otr_your_key" });
const results = await client.managedInboxes.searchDomains("yourbrand");
```
</RequestExample>

<ResponseExample>
```json
{
  "data": {
    "query": "yourbrand",
    "label": "yourbrand",
    "exact": [
      { "domain": "yourbrand.com", "inOrder": false, "available": false, "banned": false, "priceCents": null, "renewalPriceCents": null },
      { "domain": "yourbrand.net", "inOrder": false, "available": true, "banned": false, "priceCents": 1400, "renewalPriceCents": 1800 }
    ],
    "suggestions": [
      { "domain": "yourbrand-mail.com", "priceCents": 1400 }
    ]
  }
}
```
</ResponseExample>

## Errors

| Status | Description |
|--------|-------------|
| `401` | Missing, invalid, revoked or expired API key |
| `403` | API key does not have the required scope: `read` |
| `400` | `Enter a name like yourbrand or yourbrand.com` when the name cannot be a domain label |
| `404` | Not found while managed mailboxes are switched off on this environment (`{"detail": "Not found"}`) |
| `422` | `q` is missing |
| `502` | `Domain search is unavailable right now. Try again in a minute.` when the registrar lookup fails |

## Rate Limit

- **100 requests per minute, per API key.** Fixed 60-second window.
- Every response includes `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` (unix epoch seconds).
- A `429` response includes a `Retry-After` header (seconds until the bucket resets).

For client-side patterns (`Retry-After`, exponential backoff, monitoring `X-RateLimit-Remaining`), see [Rate Limiting](/rate-limiting).