Prisms API

Carbon Arc maintains a public Prisms API that provides programmatic access to every live Carbon Arc Prism, including its title, category, questions, underlying Insight, entities, and growth and share time series.

Each Prism answers a specific market or competitive question using a curated set of entities, such as companies or categories, and relative Carbon Arc data.

The actual Back to School Ad Spend Prism, for example, compares retail categories, not companies.

Use it to bring Carbon Arc Prisms into your own applications, research workflows, dashboards, or other external experiences.

---

1. Overview

Carbon Arc Prisms are curated, public data views designed to answer specific market or competitive questions.

Each Prism combines:

• A specific market or competitive question
• One underlying Carbon Arc Insight
• A curated set of entities
• Growth and share data over time

The public Prisms API exposes the complete catalog through a single endpoint:

GET /v2/public-prisms

One request returns every live Prism and its underlying entity-level time series.

API reference

Property	Value
Endpoint	GET /v2/public-prisms
Authentication	None
Parameters	None
Format	JSON
Pagination	None

The endpoint is public and does not require an API key or Carbon Arc account.

Base URL: https://api.carbonarc.co

Prisms API: https://api.carbonarc.co/v2/public-prisms

---

2. Terms of Use

The API response includes the current Prisms Terms of Use in tou.tou_content.

Use of Prism data is subject to these terms. Applications should read and handle the returned Terms of Use rather than assuming they are static.

In particular, the public Prisms API is intended for permitted research and informational use. Certain forms of redistribution, commercial use, automated extraction, and financial use may require explicit written consent from Carbon Arc.

Review tou.tou_content before building or distributing an integration using Prism data.

---

3. Quickstart

Fetch the current catalog of live Prisms with a single request.

cURL

curl -s https://api.carbonarc.co/v2/public-prisms | jq '.prisms[0]'

Python

import requests

BASE_URL = "https://api.carbonarc.co"

response = requests.get(
    f"{BASE_URL}/v2/public-prisms",
    timeout=10
)
response.raise_for_status()

payload = response.json()

print(f"{len(payload['prisms'])} live Prisms")

first = payload["prisms"][0]
print(first["title"], "-", first["question"])

JavaScript

const BASE_URL = "https://api.carbonarc.co";

const response = await fetch(`${BASE_URL}/v2/public-prisms`);

if (!response.ok) {
  throw new Error(`Prisms request failed: ${response.status}`);
}

const { tou, prisms } = await response.json();

console.log(`${prisms.length} live Prisms`);
console.log(prisms[0].title, "-", prisms[0].question);

The response contains:

• prisms: Every currently live Prism, sorted by category and title
• tou: Terms of Use associated with the public Prism data

---

4. Authentication

No authentication is required.

GET /v2/public-prisms does not require:

• An API key
• A bearer token
• A Carbon Arc account
• A signed request

Because the endpoint is public, there are no credentials to manage or rotate.

---

5. Data model

The Prisms API follows a simple hierarchy:

Prism
  └── Entities
        ├── MTD YoY
        ├── MTD Share
        ├── Historical YoY
        └── Historical Share

Prism

A Prism represents one published, data-backed view of a market or competitive question.

For example:

Which retail categories are increasing ad spend the most?

Each Prism contains one underlying Carbon Arc Insight and a set of entities to compare.

Entity

Entities are the objects being compared within a Prism. Depending on the Prism, these may represent companies, categories, or other Carbon Arc entity types.

Each entity includes:

• A stable entity_id
• An entity_representation describing its type
• A human-readable entity_name
• Growth time series
• Share time series

Treat entity_representation as a dynamic field rather than a fixed enum.

Identifiers

Field	Description
prism_id	Stable identifier for the Prism
insight_id	Identifier for the underlying Carbon Arc Insight
entity_id	Stable Carbon Arc identifier for an entity
order_id	Audit reference associated with the current Prism snapshot

entity_id can be particularly useful when tracking the same entity across multiple Prisms.

---

6. Understanding Prism values

Prisms expose relative metrics, not absolute values.

The API returns measures such as:

• Year-over-year growth
• Share within the Prism's selected entity set

It does not return the underlying absolute dollar value, transaction count, unit count, or other raw metric.

For example:

{
  "date": "2026-09-01",
  "value": 128.6
}

A value of 128.6 represents 128.6%, not 1.286.

Share values should also be interpreted within the context of the Prism. Because each Prism contains a curated set of entities rather than the entire market, entity shares are not guaranteed to sum to 100%.

---

7. Endpoint reference

GET /v2/public-prisms

Returns every currently live Prism.

Use this endpoint whether you need the complete catalog or a specific Prism. If you only need one Prism, fetch the catalog and select it client-side.

Authentication

None.

Path parameters

None.

Query parameters

None.

Filtering, searching, sorting, and pagination are not currently supported server-side.

Request body

None.

Example request

GET /v2/public-prisms HTTP/1.1
Host: api.carbonarc.co
Accept: application/json

Example response

{
  "tou": {
    "tou_content": "<p>...</p>"
  },
  "prisms": [
    {
      "title": "Back to School Ad Spend",
      "window": {
        "start": "2025-09-01",
        "end": "2026-09-12"
      },
      "category": "Advertising",
      "entities": [
        {
          "entity_id": 798,
          "entity_name": "Broadline Retail",
          "entity_representation": "category",
          "mtd_yoy": [
            {
              "date": "2026-09-01",
              "value": 128.6
            },
            {
              "date": "2026-09-02",
              "value": 133.03
            }
          ],
          "mtd_share": [
            {
              "date": "2026-09-01",
              "value": 90.87
            },
            {
              "date": "2026-09-02",
              "value": 90.86
            }
          ],
          "hist_yoy": [
            {
              "month": "2026-07",
              "value": 134.44
            },
            {
              "month": "2026-08",
              "value": 131.29
            }
          ],
          "hist_share": [
            {
              "month": "2026-07",
              "value": 89.22
            },
            {
              "month": "2026-08",
              "value": 87.15
            }
          ]
        }
      ],
      "order_id": "640f5a94-a41a-464b-a0ae-b7bb0aa1bb63",
      "prism_id": "5a772bf9-f662-426c-9836-9672cd703560",
      "question": "Which retail categories are increasing ad spend the most?",
      "question_share": "Which retail categories are capturing the most ad spend?",
      "insight_id": 245,
      "insight_label": "Advertising Spend",
      "data_through": "2026-09-09",
      "last_refreshed_at": "2026-09-12T19:26:14.955018+00:00",
      "note": null,
      "published_at": "2026-08-20T22:29:57.376184+00:00"
    }
  ]
}

---

8. Response schema

Top-level response

Field	Type	Description
tou	object or null	Terms of Use associated with the public Prism data
prisms	array	All currently live Prisms

The prisms array is returned sorted by category and title.

Prism

Field	Type	Description
prism_id	string	Stable Prism identifier
title	string	Display title
category	string	Prism category
question	string or null	Growth question answered by the Prism
question_share	string or null	Share question answered by the Prism
note	string or null	Additional context or caveat when applicable
insight_id	integer	Identifier for the underlying Carbon Arc Insight
insight_label	string	Display name for the underlying Insight
window	object	Start and end dates for the Prism window
data_through	date or null	Most recent date represented by the underlying data
last_refreshed_at	ISO 8601 datetime	Time the current snapshot was computed
published_at	ISO 8601 datetime or null	Time the Prism was published
order_id	string	Audit reference for the current snapshot
entities	array	Entities and time series included in the Prism

note and published_at may not be present on some older Prisms. Integrations should treat both as optional.

Entity

Field	Type	Description
entity_id	integer	Stable Carbon Arc entity identifier
entity_representation	string	Entity type, such as company or category
entity_name	string	Human-readable entity name
mtd_yoy	array	Month-to-date cumulative YoY series, returned by date
mtd_share	array	Month-to-date cumulative share series, returned by date
hist_yoy	array	Historical YoY series, returned by month
hist_share	array	Historical share series, returned by month

Each mtd_* observation contains a date and value. Each hist_* observation contains a month and value.

All series values are returned as percentages.

---

9. Filtering and searching

The API does not currently support server-side filtering, searching, or sorting parameters.

Instead, fetch the catalog once and work with the response locally.

Filter by category

advertising = [
    prism
    for prism in payload["prisms"]
    if prism["category"] == "Advertising"
]

Find Prisms containing an entity

def prisms_for_entity(prisms, entity_id):
    return [
        prism
        for prism in prisms
        if any(
            entity["entity_id"] == entity_id
            for entity in prism["entities"]
        )
    ]

Search titles and questions

def search_prisms(prisms, term):
    term = term.lower()

    return [
        prism
        for prism in prisms
        if term in prism["title"].lower()
        or term in (prism.get("question") or "").lower()
    ]

Because the complete Prism catalog is returned in one request, client-side filtering is the recommended approach.

---

10. Pagination

Pagination is not required.

GET /v2/public-prisms returns every live Prism in a single response. There are no offset, limit, cursor, or page parameters.

Do not assume a fixed number of Prisms. Carbon Arc will continue adding and updating Prisms over time, so integrations should iterate over the returned prisms array dynamically.

---

11. Data freshness

Prisms separate the display window from the freshness of the underlying data.

Field	Meaning
window.start	Beginning of the Prism's current display window
window.end	End of the Prism's current display window
data_through	Latest date represented by the underlying data
last_refreshed_at	When Carbon Arc last computed the Prism
published_at	When the Prism was originally published

window.end and data_through may differ. Use data_through when communicating how current the underlying data is.

The endpoint returns Carbon Arc's current published snapshot rather than running a new data query for every API request. As a result, repeated requests between Prism refreshes should return the same underlying data.

---

12. Rate limits and caching

There is currently no documented per-caller rate limit for GET /v2/public-prisms.

Because Prisms update on Carbon Arc's own refresh cadence, applications should cache the response rather than request the full catalog on every page view.

A simple production pattern is:

Carbon Arc Prisms API
        ↓
Fetch + retry
        ↓
Application cache
        ↓
Your application

Recommended practices:

• Cache the response based on your application's freshness requirements.
• Set a reasonable HTTP timeout.
• Retry transient network and server errors with backoff.
• Avoid polling the endpoint unnecessarily.
• Use prism_id rather than array position as the stable identifier in your application.

---

13. Error handling

A successful request returns:

200 OK

with:

{
  "tou": {},
  "prisms": []
}

For unsuccessful requests, integrations should handle non-200 responses defensively.

Response	Recommended action
200	Process the response
5xx	Retry with exponential backoff
Network timeout	Retry, then surface an error if the request continues to fail
Unexpected 4xx	Validate the host and request configuration before retrying

Because the endpoint does not require authentication or accept request parameters, most integrations should have very little request-side error handling.

---

14. Common workflows

Render Prisms by category

The API already returns Prisms sorted by category and title, making it straightforward to group the catalog for display.

from itertools import groupby

prisms = payload["prisms"]

by_category = {
    category: list(group)
    for category, group in groupby(
        prisms,
        key=lambda prism: prism["category"]
    )
}

Track an entity across Prisms

Because entity_id identifies an entity within Carbon Arc, you can use it to find every Prism containing that entity.

def latest_value(series):
    return series[-1]["value"] if series else None

def entity_snapshot(prisms, entity_id):
    results = []

    for prism in prisms:
        for entity in prism["entities"]:
            if entity["entity_id"] == entity_id:
                results.append({
                    "prism": prism["title"],
                    "category": prism["category"],
                    "latest_yoy": latest_value(entity["mtd_yoy"]),
                    "latest_share": latest_value(entity["mtd_share"])
                })

    return results

Detect refreshed Prisms

Use last_refreshed_at to identify Prisms that have changed since your previous sync.

def changed_prisms(previous_by_id, current_prisms):
    return [
        prism
        for prism in current_prisms
        if prism["prism_id"] not in previous_by_id
        or previous_by_id[prism["prism_id"]]["last_refreshed_at"]
           != prism["last_refreshed_at"]
    ]

To detect removed Prisms, also compare previously stored prism_id values against the current response.

---

15. Production recommendations

For most integrations, the Prisms API should remain simple. One request provides the complete catalog, so there is no authentication lifecycle, pagination state, or server-side query model to manage.

A few practices will make the integration more resilient:

• Cache the catalog: Match your refresh cadence to how frequently you need new Prism data rather than fetching on every request.
• Set a timeout: Do not leave HTTP requests unbounded.
• Retry transient failures: Use backoff for network errors and 5xx responses.
• Key on prism_id: Do not rely on a Prism's position in the returned array.
• Track last_refreshed_at: Store it alongside Prism data if freshness matters to your application.
• Parse defensively: Treat documented optional fields as optional and ignore new fields you do not yet use.
• Treat categories as dynamic: New categories may be introduced as Carbon Arc publishes additional Prisms.
• Review Terms of Use: Read the current tou.tou_content before building or distributing an integration.

---

16. Quick reference

I want to...	Approach
Get every live Prism	GET /v2/public-prisms
Get one Prism	Fetch the catalog and filter on prism_id
Filter by category	Filter category client-side
Find Prisms containing an entity	Search entities[].entity_id
Track data freshness	Use data_through and last_refreshed_at
Detect refreshed Prisms	Compare last_refreshed_at with your stored snapshot
Display Terms of Use	Use tou.tou_content when present

---

17. Important considerations

• Prism data is relative: Growth and share series contain relative values rather than the underlying absolute metric.
• Entities vary by Prism: Entities may represent companies, categories, or other entity types. Use entity_representation to determine the type.
• Series have different time keys: mtd_* series use date; hist_* series use month.
• Freshness is explicit: Use data_through to determine how current the underlying data is.
• Optional fields may be absent: Handle fields such as note and published_at defensively.
• Categories and entity representations are dynamic: Do not hardcode a fixed list.
• The catalog changes over time: Use prism_id rather than array position as the stable Prism identifier.
• Terms govern use: Review the current tou.tou_content returned by the API before using or distributing Prism data.