Last Updated: September 22nd, 2025

Scrunch APIs are hosted under the api.scrunchai.com domain.

API access is authenticated via a shared secret bearer token, which you can pass us in the standard Authentication header.

For example, via curl:

curl -H "Authorization: Bearer ${SCRUNCH_API_TOKEN}" "https://api.scrunchai.com/v1/${SCRUNCH_BRAND_ID}/prompts"

Scrunch API tokens can be scoped for:

A Brand is Scrunch's unit of organization for data & reporting, including clients / customers of partners. All Scrunch query APIs and most data APIs operate for a specific brand's context. We currently do not expose cross-brand reporting capabilities (e.g. each brand must be queried individually) but we may support this in the future. You may safely share read-only brand-scoped API tokens (or data access methods that use an API token under the hood, such as a BI connector) with clients if needed.

An Organization represents a Scrunch AI customer, regardless of the number of brands they have. Organization-scoped API keys can be used for internal reporting or for programmatically configuring many Scrunch brands (e.g. automated client onboarding.) In agency or MSP scenarios, organization-scoped keys should not be exposed to individual clients, as this would enable them to access other client data.

The operational scopes Scrunch supports are:

By default, API credentials are scoped for all brands attached to your organization, including future brands created via the web application or via API. However, with the exception of the List Brands and Create Brand APIs, all API calls must include a specific brand ID to function. The API does not yet support e.g. running reporting queries across multiple brands at the same time.

If desired, API credentials can be restricted to specific brand(s) for reporting purposes – for example, if you are an agency and are required to integrate into client reporting tools, Scrunch can provide an API credential that is limited to only their specific brand(s) data. Reach out to support@scrunchai.com if this is needed.

Organization administrators (typically the person who signed up for Scrunch AI) can create API keys by accessing the Organization > Settings menu item in the left sidebar. If you can't locate your organization administrator, or they don't see this option, contact us at support@scrunchai.com.

Navigate to "API Keys" and click "Add API Key".

Configure the scopes appropriately (see above section for scope definitions.)

The API always returns responses in JSON format.

Query APIs accept parameters via query parameters:

curl -H "Authorization: Bearer ${SCRUNCH_API_TOKEN}" https://api.scrunchai.com/v1/${SCRUNCH_BRAND_ID}/prompts?stage=awareness

Mutation APIs generally accept JSON request bodies.

curl -H "Content-Type: application/json" -H "Authorization: Bearer ${SCRUNCH_API_TOKEN}" -d '{"prompt": "Sample prompt", "tags": ["tag_a", "tag_b"]}' https://api.scrunchai.com/v1/${SCRUNCH_BRAND_ID}/prompts

The Query API allows retrieval of analytics data across various dimensions and metrics in a flexible way. Generally, the metrics and dimensions operate identically to the filters & metrics in the Scrunch web application. The API is designed to support integration with common reporting tools.

curl -H "Authorization: Bearer ${SCRUNCH_API_TOKEN}" https://api.scrunchai.com/v1/${SCRUNCH_BRAND_ID}/query?fields=tag,brand_presence_percentage

The Query API auto-aggregate metrics for any specified dimensions. For example, if you specify ?fields=tag,brand_presence_percentage you will receive the average brand presence for each tag.

By default the Query API is configured to return a very large number of results (up to 50,000) for ease of integration into BI tools that may not support paginating results sets. Pagination is supported via limit and offset parameters. However, if you find yourself needing to paginate the Query API, it's highly likely that you are specifying too granular a combination of fields.

The Query API allows specifying many dimensions for reporting at once. Specifying granular combinations of dimensions (e.g. date,prompt_id,source_url,competitor_id) may cause very large result sets – upwards of 1 million rows for customers with many prompts configured.

In our experience, specifying all dimensional fields together does not produce usable data sets – it's often better to query separately for, for example, date,prompt_id,prompt,persona_id,ai_platform,branded,responses,brand_presence_percentage,brand_sentiment_score,brand_position_score and then date,prompt_id,source_url,source_type and then date,prompt_id,competitor_name,competitor_presence_percentage and stitch them together.

Combining all these dimensions into one query will, for instance, give you a brand_presence_percentage metric that is specific to just responses for a particular prompt where a particular competitor shows up and a particular source URL is also cited. We find metrics at this level are usually not useful for straightforward aggregation and reporting. If you're looking for raw data for more sophisticated analysis, please contact your CSM for access to the Responses API.

The following dimensional fields are many-to-many with prompts and therefore can produce large result sets when combined:

Currently the Query API only supports filtering on date range. Pagination parameters can also be set (see above.)

Specify these in the fields= array to retrieve them. Dimensions determine how metrics are grouped. Querying a dimension by itself will simply give you the unique values for that dimension. Querying a metric by itself will give you the overall aggregate of that metric, which may or may not be useful.