Prisms Python SDK

REST reference (catalog routes and response shapes): Prisms API

Prisms are ready-made charts Carbon Arc keeps up to date: one metric insight (for example daily app downloads or credit card spend) applied to a fixed set of companies or brands. The numbers you see on the public Prisms page are the same numbers you can pull with the Python SDK and your API token.

This guide explains what Prisms are, what changed in the API, and how to use client.prisms without needing to know the backend route names.

What you get (and what you do not)

Prisms show relative movement, not raw totals.

Year-over-year (YoY) index — how much an entity is up or down versus the same period last year, on Carbon Arc’s indexed scale.
Share of group — that entity’s share of the combined group in the prism.

You will not see absolute dollars, visits, or download counts in Prism responses. To go deeper, use the framework on a single prism to buy the same underlying Carbon Arc data in Explore (see Reproduce the numbers with Explore below).

Arrays are a related product: one equal-weight average of all entities in a source prism, rolled up to a monthly growth series. An Array is not a prism; it lives in the arrays list, not in prisms. See Arrays on the Platform docs.

What changed (in plain terms)

Carbon Arc split “everything on the Prisms page” into clear API entry points behind your token:

What you want	SDK method	Notes
Full page snapshot (terms + all prisms + all arrays)	`client.prisms.get_prism_catalog()` or `client.prisms.list_prisms()` with no filters	Same content as the public page, minus legacy `indexes`. Includes `tou` (terms of use).
Same snapshot, no token (browser / public tools)	`client.prisms.get_public_prisms()`	Unchanged public endpoint; may still include empty legacy `indexes`.
Only the arrays list	`client.prisms.list_arrays()`	`{ "arrays": [...] }` — same array objects as in the catalog.
One array by id	`client.prisms.get_array(array_id)`	404 if the id is unknown or malformed.
One prism by id (includes purchase recipe)	`client.prisms.get_prism(prism_id)`	Includes `framework` for Explore.
Prisms matching an insight and/or entity	`client.prisms.list_prisms(insight_id=…)` etc.	Each match includes `framework`.

Important habits:

Do not call the API as “list all prisms” with an empty /v2/prisms URL. That returns 400 and tells you to use /v2/prisms/catalog (or list_prisms() with no arguments in the SDK).
Catalog and array routes require a valid API token. Any normal API token works; there is no separate “Prisms plan” and no charge per read.
Paths like /catalog and /arrays are not prism UUIDs. Older servers mistakenly treated those words as ids and returned errors; current APIs register catalog and array routes before the single-prism route.

Authenticated catalog responses use private caching headers so shared caches must not replay your data to someone else without a token. The public Prisms endpoint stays public for browser use.

Setup

Get an API token from your Carbon Arc account (Profile in the app), then:

from carbonarc import CarbonArcClient

client = CarbonArcClient(
    host="https://api.carbonarc.co",  # or your dev/staging host
    token="your_api_token_here",
)

Install the SDK if you have not already:

pip install carbonarc

For dataframe helpers:

from carbonarc.prisms import array_to_dataframe, prism_to_dataframe

See API Authentication if you need token setup details.

Step 1 — Browse the catalog

Start here when you want the same overview as the Prisms page: titles, categories, entity lists, and chart series without the purchase recipe on every row.

catalog = client.prisms.get_prism_catalog()
# Same as:
catalog = client.prisms.list_prisms()

print(len(catalog["prisms"]), "prisms")
print(len(catalog["arrays"]), "arrays")
print("terms of use present:", "tou" in catalog)

Each prism in the catalog includes metadata and time series on its entities (mtd_yoy, mtd_share, hist_yoy, hist_share). It does not include framework. Use data_through on each prism to see how fresh the data is (the last day with real upstream data, which can lag the calendar).

For a shorter walkthrough with screenshots, see Browse Prisms and Read Index Values.

Step 2 — Open one prism

When you know a prism_id (from the catalog or from the app), fetch the full snapshot with the framework you need for Explore:

prism_id = catalog["prisms"][0]["prism_id"]
prism = client.prisms.get_prism(prism_id)

print(prism["title"])
print(prism["data_through"])
print("framework ready:", "framework" in prism)

If the id is wrong or the prism is not published, the API returns 404.

Step 3 — Find prisms by insight or entity

Use filters when you care about a metric (insight_id) and/or a company or brand (entity_id, optionally with entity_representation):

# Example: prisms tied to one insight (id from catalog or docs)
matches = client.prisms.list_prisms(insight_id=775)

for p in matches["prisms"]:
    print(p["title"], p["prism_id"])

Expect zero, one, or many results. One insight often spans several entity groups; one entity can appear in several prisms. Do not assume exactly one match.

Filtered results use the same shape as get_prism: each prism includes framework.

An entity is (carc_id, representation)

A carc_id alone is ambiguous. The same real-world thing has a different id per representation. Supply entity_representation when you know it. Use the Ontology API to resolve names to ids.

Step 4 — Work with Arrays

Arrays aggregate one prism’s entities into a single monthly series:

arrays = client.prisms.list_arrays()["arrays"]
# Or use catalog["arrays"] — same objects.

array = client.prisms.get_array(arrays[0]["array_id"])
print(array["title"], "entities:", array["entity_count"])

In level, a month with a null value means some entities were missing that month; a month missing entirely means the month was not complete yet. Check coverage and data_through when you interpret the last point.

Step 5 — Put series in a dataframe

For notebooks and analysis, flatten nested series into tables:

df_prism = prism_to_dataframe(prism)
# Columns: entity_id, entity_representation, entity_name, series, period, value

df_array = array_to_dataframe(array)
# Columns: array_id, title, month, value

Reproduce the numbers with Explore

Prisms are read-only reference views. Carbon Arc computes and publishes them for you. When you need the underlying panel data behind a chart, use the prism’s framework with Explore — the same purchase shape as other framework buys.

framework = prism["framework"]

# date_range is sometimes omitted; set a window that covers your analysis.
framework["filters"].setdefault(
    "date_range",
    {"start_date": "2024-09-01", "end_date": "2026-09-16"},
)

order = client.explorer.build_framework(**framework)
purchase = client.explorer.buy_frameworks(order)
# Then load framework data with explorer.get_framework_data(...) as in other tutorials.

Naming trap: inside framework, entities use carc_id and representation. On the prism’s chart entities they appear as entity_id and entity_representation. The values match, but you must use the framework field names when buying.

End-to-end pricing, purchase, download, and index reproduction: How to Buy Prisms Data.

Quick reference (SDK)

catalog = client.prisms.list_prisms()
prism = client.prisms.get_prism("<prism-uuid>")
matches = client.prisms.list_prisms(insight_id=775, entity_id=36003)
arrays = client.prisms.list_arrays()["arrays"]
array = client.prisms.get_array("<array-uuid>")
public = client.prisms.get_public_prisms()  # no token required on the HTTP call

prism_to_dataframe(prism)
array_to_dataframe(array)

get_prisms is an alias for list_prisms.

Browse Prisms and Read Index Values — step-by-step walkthrough (no token spend)
How to Buy Prisms Data — purchase underlying panel data and recompute indexes
Prisms API — REST endpoints and public catalog
Intro to Prisms — read charts in the product UI
Arrays — equal-weight sector benchmarks
Ontology API — resolve insight and entity ids for filters

Questions? Contact support@carbonarc.co.