Prerequisites
- A Scrunch workspace
- An API key with Responses access
- A brand ID for the brand you want to fetch responses for
The Responses API returns row-level data. It is ideal for warehouses, BI tools, audits, DE workflows, and custom analysis.
You may need to reach out to your Scrunch rep for Responses API access
Call the API
cURL
Python
JavaScript / TypeScript
Set your API key
export SCRUNCH_API_KEY="your-api-key-here"
export SCRUNCH_BRAND_ID="your-brand-id"
Call the Responses API
This example retrieves responses for a single day (Scrunch recommends syncing by date windows).curl "https://api.scrunchai.com/v1/$SCRUNCH_BRAND_ID/responses?start_date=2025-01-01&end_date=2025-01-02&limit=100" \
-H "Authorization: Bearer $SCRUNCH_API_KEY" \
-H "Accept: application/json"
{
"total": 128,
"limit": 100,
"offset": 0,
"items": [
{
"id": "resp_01jk93mc9p",
"created_at": "2025-01-01T05:12:41.000Z",
"prompt_id": "pr_01hd8j39s",
"prompt": "Which mattress brands are recommended for side sleepers?",
"platform": "chatgpt",
"brand_present": true,
"brand_sentiment": "positive",
"brand_position": 1,
"response_text": "For side sleepers, the best mattresses tend to...",
"citations": [
{
"url": "https://www.example.com/review",
"title": "2024 mattress comparison",
"source_type": "other"
}
],
"competitors": [
{ "name": "Casper", "present": true, "sentiment": "neutral" },
{ "name": "Purple", "present": true, "sentiment": "positive" }
],
"tags": ["mattress", "comparison"],
"stage": "evaluation"
}
]
}
Paginate through responses
Use the offset parameter to retrieve subsequent batches:curl "https://api.scrunchai.com/v1/$SCRUNCH_BRAND_ID/responses?start_date=2025-01-01&end_date=2025-01-02&limit=100&offset=100" \
-H "Authorization: Bearer $SCRUNCH_API_KEY"
Install dependencies
pip install requests pandas
Create your script
import requests
import pandas as pd
API_KEY = "your-api-key"
BRAND_ID = "your-brand-id"
BASE_URL = f"https://api.scrunchai.com/v1/{BRAND_ID}/responses"
params = {
"start_date": "2025-01-01",
"end_date": "2025-01-02",
"limit": 100,
"offset": 0
}
all_rows = []
while True:
response = requests.get(
BASE_URL,
headers={"Authorization": f"Bearer {API_KEY}"},
params=params,
timeout=60
)
response.raise_for_status()
data = response.json()
items = data["items"]
all_rows.extend(items)
if params["offset"] + params["limit"] >= data["total"]:
break
params["offset"] += params["limit"]
df = pd.DataFrame(all_rows)
print(df.head())
Run your script
python responses_quickstart.py
Create your script
import axios from "axios";
const API_KEY = "your-api-key";
const BRAND_ID = "your-brand-id";
async function fetchResponses() {
let offset = 0;
const limit = 100;
const all = [];
while (true) {
const res = await axios.get(
`https://api.scrunchai.com/v1/${BRAND_ID}/responses`,
{
headers: { Authorization: `Bearer ${API_KEY}` },
params: {
start_date: "2025-01-01",
end_date: "2025-01-02",
limit,
offset,
},
}
);
all.push(...res.data.items);
if (offset + limit >= res.data.total) break;
offset += limit;
}
console.log(all.slice(0, 3));
}
fetchResponses().catch(console.error);
When to use the Responses API
Use the Responses API when you need:
- Full AI-generated answers
- Citations and source URLs used in responses
- Per-response presence, position, sentiment
- Competitor mentions
- Metadata (stage, tags, topics, platform, persona)
- Warehouse or BI-level granularity
Next steps
