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

# Spyglass API

> Query Spyglass ad intelligence from your own code over HTTP.

The Spyglass API gives you the same brand, creative, and landing-page data the
app runs on. Four endpoints, one bearer key, JSON in and out.

## Get a key

1. Open **Settings → API** in the [dashboard](https://app.spyglass.so).
2. Click **Create key** and give it a name you'll recognize later.
3. Copy the key. It starts with `sg_live_` and is shown **once** — we store only
   a hash, so if you lose it you'll need to create another.

Keys are private to the person who created them, and scoped to the team they
were created for. If you leave that team, the key stops working.

## Your first call

Every endpoint is brand-scoped except search, so start by resolving a brand.

```bash theme={null}
curl -X POST https://app.spyglass.so/api/v1/brands/search \
  -H "Authorization: Bearer $SPYGLASS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode": "brand_name", "brandNames": ["Nike"], "type": "BRAND", "count": 3}'
```

```json theme={null}
{
  "brands": [
    {
      "id": "1234567890",
      "name": "Nike",
      "verified": true,
      "igFollowers": 302000000,
      "igEngagementRate": 0.0142
    }
  ],
  "count": 1
}
```

Take the `id` and ask what that brand is running:

```bash theme={null}
curl -X POST https://app.spyglass.so/api/v1/brands/1234567890/media \
  -H "Authorization: Bearer $SPYGLASS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode": "smart", "userRequest": "video ads about comfort", "limit": 20}'
```

## What you can ask for

| Endpoint                         | Answers                                                 |
| -------------------------------- | ------------------------------------------------------- |
| `POST /brands/search`            | Which brand is this? Who else is in this space?         |
| `POST /brands/{id}/media`        | What creatives is this brand running?                   |
| `GET /brands/{id}/insights`      | What hooks, USPs, personas and formats does it lean on? |
| `GET /brands/{id}/landing-pages` | Where does its ad traffic go?                           |

Full parameters and response schemas are in the
[API reference](/api-reference).

## Before you build

Three things worth knowing up front, because they shape how you write the
client:

* **Calls cost credits, per row returned.** Bound every call with `limit` or
  `count`. See [Billing](/billing).
* **Nothing is paginated.** `count` is the number of rows in *this* response,
  not a total. See [Conventions](/conventions).
* **It's server-to-server.** There's no CORS, so calls must come from your
  backend, not a browser.