spyglass-sdk 0.1.5

The API layer for the social internet

Official Python SDK for the Spyglass API — search brands, creators, and the ads they run.

spyglass-sdk is the official Python client for the Spyglass API with both synchronous (Spyglass) and asynchronous (AsyncSpyglass) clients. Resolve brands and creators, search across millions of Meta, Instagram, and TikTok creatives with natural-language briefs or structured filters, and extract hooks, personas, landing pages, and public comments.

Looking for TypeScript / Node.js? See spyglass-so/spyglass-typescript (npm install @spyglasshq/sdk).

Installation

pip install spyglass-sdk
# or
uv add spyglass-sdk

Quickstart

Create an API key in Settings → API. Keys start with sg_live_ and are shown once.

import os
from spyglass import Spyglass

client = Spyglass(token=os.environ["SPYGLASS_API_KEY"])

# 1. Resolve a brand
result = client.search_brands(names=["Nike"], limit=1)

if result.brands:
    brand = result.brands[0]

    # 2. Search the creatives that brand is running
    media_result = client.search_media(
        brand_id=brand.id,
        query="marathon running shoes comfort",
        limit=10,
    )

    for ad in media_result.media:
        print(ad.id, ad.hook, ad.core_angle, ad.url)

Async Usage

Use AsyncSpyglass for non-blocking calls with asyncio:

import asyncio
import os
from spyglass import AsyncSpyglass

client = AsyncSpyglass(token=os.environ["SPYGLASS_API_KEY"])


async def main() -> None:
    result = await client.search_brands(names=["Nike"], limit=3)
    for brand in result.brands:
        print(brand.id, brand.name)


asyncio.run(main())

API Reference Overview

Full parameters and response schemas are documented in reference.md and at docs.spyglass.so.

Indexing a New Account

If Spyglass doesn't have a brand or creator yet, queue it by website or social profile URL (POST /account/index is free) and poll until status is "ready":

import time

indexed = client.account.index(website_url="https://www.on.com")

status = indexed.status
while status == "indexing":
    time.sleep(3)
    check = client.account.index_status(id=indexed.brand_id)
    status = check.status

if status in ("ready", "already_exists"):
    account = client.account.get(id=indexed.brand_id)
    print("Indexed account:", account.name)

Error Handling

Non-2xx responses raise an ApiError with status code and parsed error body:

from spyglass.core.api_error import ApiError

try:
    client.search_brands(names=["Nike"], limit=5)
except ApiError as e:
    print(e.status_code, e.body)

Advanced Options

Retries & Timeouts

Requests default to a 60-second timeout and up to 2 automatic retries with exponential backoff on 408, 409, 429, and 5xx responses. Override at the client or per-request level:

client = Spyglass(token="...", timeout=30.0, max_retries=3)

response = client.search_brands(
    names=["Nike"],
    limit=5,
    request_options={"timeout_in_seconds": 15, "max_retries": 1},
)

Raw Response & Headers

Use .with_raw_response to inspect HTTP headers and status codes:

raw = client.with_raw_response.search_brands(names=["Nike"], limit=1)
print(raw.status_code)
print(raw.headers)
print(raw.data.brands)

Custom HTTPX Client

Pass a custom httpx.Client or httpx.AsyncClient for custom proxies or transport settings:

import httpx
from spyglass import Spyglass

client = Spyglass(
    token="...",
    httpx_client=httpx.Client(proxy="http://proxy.example.com"),
)

Billing & Conventions

• Credits: Most calls spend monthly credits per row returned (count in the response). Always bound requests with limit. See Billing docs.
• Pagination: Page through results with offset and limit. count is the number of rows in the current response.
• Server-to-server: Call the API from your backend, data pipeline, or agent runtime.

Support

• Documentation: docs.spyglass.so
• Issues: github.com/spyglass-so/spyglass-python/issues
• Email: support@spyglass.so

License

MIT