Responses API Quickstart - Scrunch API Docs

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"

Example output:

{
  "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

Install Axios

npm install axios

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);

Run your script

node responses.js

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

Responses API overview

Explore the response schema and filtering options.

[Coming soon] ETL best practices

Learn how to sync Responses into BigQuery, Snowflake, or Redshift.

Query API

Use Query for trends, aggregates, comparisons, and dashboards.

​Prerequisites

​Call the API

​When to use the Responses API

​Next steps

Responses API overview

[Coming soon] ETL best practices

Query API

Prerequisites

Call the API

When to use the Responses API

Next steps