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

# Responses API Quickstart

> Use the Responses API to retrieve full AI answers, citations, sentiment, competitors, and metadata for every Scrunch prompt execution.

### 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.

<Note>
  You may need to reach out to your Scrunch rep for Responses API access
</Note>

***

### Call the API

<Tabs>
  <Tab title="cURL">
    <Steps>
      <Step title="Set your API key">
        ```bash theme={null}
        export SCRUNCH_API_KEY="your-api-key-here"
        export SCRUNCH_BRAND_ID="your-brand-id"
        ```
      </Step>

      <Step title="Call the Responses API">
        This example retrieves responses for a single day (Scrunch recommends syncing by date windows).

        ```bash theme={null}
        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:**

        ```json theme={null}
        {
          "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"
            }
          ]
        }
        ```
      </Step>

      <Step title="Paginate through responses">
        Use the `offset` parameter to retrieve subsequent batches:

        ```bash theme={null}
        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"
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Python">
    <Steps>
      <Step title="Install dependencies">
        ```bash theme={null}
        pip install requests pandas
        ```
      </Step>

      <Step title="Create your script">
        ```python theme={null}
        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())
        ```
      </Step>

      <Step title="Run your script">
        ```bash theme={null}
        python responses_quickstart.py
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="JavaScript / TypeScript">
    <Steps>
      <Step title="Install Axios">
        ```bash theme={null}
        npm install axios
        ```
      </Step>

      <Step title="Create your script">
        ```javascript theme={null}
        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);
        ```
      </Step>

      <Step title="Run your script">
        ```bash theme={null}
        node responses.js
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

***

## 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

<CardGroup cols={3}>
  <Card title="Responses API overview" icon="list-tree" href="/api-reference/responses/overview">
    Explore the response schema and filtering options.
  </Card>

  <Card title="[Coming soon] ETL best practices" icon="database">
    Learn how to sync Responses into BigQuery, Snowflake, or Redshift.
  </Card>

  <Card title="Query API" icon="chart-line" href="/api-reference/query/overview">
    Use Query for trends, aggregates, comparisons, and dashboards.
  </Card>
</CardGroup>