Events API — User Guide

Use the Carbon Arc Python SDK to discover events in the ontology, find related entities and insights, and build event-based frameworks in the Builder.

This guide reflects the Events SDK methods (see the Events notebook in the SDK repo for a runnable walkthrough).

Setup

import os
from dotenv import load_dotenv
from carbonarc import CarbonArcClient

load_dotenv()

client = CarbonArcClient(
    host="https://api.carbonarc.co",
    token=os.getenv("CARBONARC_TOKEN"),
)

Install the SDK:

pip install carbonarc

Get an API token from https://app.carbonarc.ai/my/profile.

Overview

Events support spans two clients:

Client	Purpose
`client.ontology`	Discover events, browse types/categories, find related entities and insights
`client.explorer`	Build, price, buy, and retrieve data for event-based frameworks

Typical flow:

Browse event types and categories
Search or filter events
Find related entities / insights for an event
Build a framework with events=[...] (pass entities=None for event-only)
Collect filters, check price, buy, and pull data

Ontology — discover events (`client.ontology`)

All ontology event endpoints live under https://api.carbonarc.co/v2/ontology/*.

List event types — `get_event_types`

Returns available event types and their representation names (e.g. entityeventp, macroeventp, industryeventp).

types = client.ontology.get_event_types()

Use these representation strings when filtering events, entities, and insights, and when building frameworks.

List event categories — `get_event_categories`

Returns categories grouped by event type. Optionally scoped to an insight or entity context.

# All categories
categories = client.ontology.get_event_categories()

# Filtered
categories = client.ontology.get_event_categories(
    event_type="Corporate Events",
    insight_id=141222,
    entity_id=26166,
    entity_representation="artist",
)

Returns: dict with an items list. Each item has event_type, categories (list of {name, id}), and skip_parent_event (bool).

Search / list events — `get_events`

Browse or search event entities. When search is provided, results are ranked by vector similarity; use min_score (0–1) to set a relevance threshold.

# Browse all (paginated)
result = client.ontology.get_events(page=1, size=20)
print(result["total"])

# Filter by entity
result = client.ontology.get_events(
    entity_id=26166,
    entity_representation="artist",
)

# Filter by insight
result = client.ontology.get_events(
    insight_id=141221,
)

# Keyword search
result = client.ontology.get_events(
    search="earnings",
    min_score=0.5,
)

Parameters (all optional unless noted):

Parameter	Type	Description
`insight_id`	`int`	Filter events linked to this insight.
`entity_id`	`int` / `str`	Filter events linked to this entity.
`entity_representation`	`str`	Entity representation (required with `entity_id`).
`search`	`str`	Keyword query for vector-based search.
`min_score`	`float`	Minimum similarity score when using `search` (0–1).
`page`	`int`	Page number (default 1).
`size`	`int`	Page size (default 100).

Each event in the response includes metadata such as event_id, event_name, event_type, and entity_domain.

Find entities for an event — `get_entities`

Existing method, extended with event filters:

entities = client.ontology.get_entities(
    event_id=2125,
    event_representation="macroeventp",
)

Find insights for an event — `get_insights`

Existing method, extended with event filters:

insights = client.ontology.get_insights(
    event_id=43505,
    event_representation="industryeventp",
)

Builder — event-based frameworks (`client.explorer`)

The Explorer client accepts an events list when building frameworks. events is keyword-only — pass it as events=[...], never positionally.

entities is a required argument, but it accepts None. For an event-only query pass entities=None (or entities=[]) explicitly; omitting it raises TypeError: build_framework() missing 1 required positional argument: 'entities'.

Each event dict requires:

event_id or event_category_id — at least one must be present and non-null
representation — event representation (e.g. "entityeventp", "macroeventp")

event_id is coerced to str by the SDK. Optional keys like event_name are passed through to the API. Category-only frameworks use event_category_id with no parent event_id.

event_id requires a parent representation

event_id is a parent event ID, so it must be paired with a parent representation — one of corpeventp, entityeventp, industryeventp, macroeventp, calendareventp (the …p forms). Pairing event_id with a child representation such as entityeventc is rejected by the API. Child representations are valid with event_category_id.

Build a framework — `build_framework`

framework = client.explorer.build_framework(
    entities=None,
    insight={"insight_id": 161215},
    filters={},
    events=[{"event_id": 166, "representation": "macroeventp"}],
)

Event-only example (no entities):

framework = client.explorer.build_framework(
    insight={"insight_id": 141202},
    filters={
        "date_resolution": "day",
        "location_resolution": "us",
        "date_range": {
            "start_date": "2024-02-29",
            "end_date": "2026-05-21",
        },
        "related_entity_name": "*",
        "related_entity_representation": "*",
    },
    entities=None,  # required argument; None means events-only
    aggregate="sum",
    events=[
        {
            "event_id": "8",
            "representation": "entityeventp",
            "event_name": "& Juliet",
        }
    ],
)

Collect filters — `collect_framework_filters`

filters = client.explorer.collect_framework_filters(framework)

Event-based frameworks may expose additional filter keys (e.g. related_entity_representation).

Filter options — `collect_framework_filter_options`

options = client.explorer.collect_framework_filter_options(
    framework=framework,
    filter_key="related_entity_representation",
)

Check price — `check_framework_price`

price = client.explorer.check_framework_price(framework)
print(price)  # e.g. 4.99

Purchase — `buy_frameworks`

order = client.explorer.buy_frameworks(order=[framework])
print(order["frameworks"])   # framework IDs
print(order["total_price"])

Retrieve data — `get_framework_data`

data = client.explorer.get_framework_data(
    framework_id=order["frameworks"][0],
)

Method reference

`client.ontology` (new / extended)

Method	Returns	Description
`get_event_types()`	`dict`	Available event types and representations.
`get_event_categories(event_type, insight_id, entity_id, entity_representation)`	`dict`	Event categories, optionally scoped.
`get_events(insight_id, entity_id, entity_representation, search, min_score, page, size)`	`dict`	Paginated event list / vector search.
`get_entities(..., event_id, event_representation)`	`dict`	Entities linked to an event.
`get_insights(..., event_id, event_representation)`	`dict`	Insights linked to an event.

`client.explorer` (extended)

Method	Change
`build_framework(entities, insight, filters, aggregate=None, *, events=None)`	Keyword-only `events` param. `entities` is required but accepts `None` for event-only queries.
`collect_framework_filters`	Works with event-based frameworks.
`collect_framework_filter_options`	May return event-specific filters.
`check_framework_price`	Prices event-based frameworks.
`buy_frameworks`	Purchases event-based frameworks.
`get_framework_data`	Retrieves purchased event framework data.

End-to-end example

from carbonarc import CarbonArcClient
import os
from dotenv import load_dotenv

load_dotenv()

client = CarbonArcClient(
    host="https://api.carbonarc.co",
    token=os.getenv("CARBONARC_TOKEN"),
)

# 1. Discover event types
client.ontology.get_event_types()

# 2. Search for an event
events = client.ontology.get_events(search="earnings")
event = events["items"][0]  # pick one from the response

# 3. Find insights tied to the event
insights = client.ontology.get_insights(
    event_id=event["event_id"],
    event_representation=event.get("entity_domain") or "entityeventp",
)

# 4. Build, price, and buy an event framework
framework = client.explorer.build_framework(
    entities=None,
    insight={"insight_id": insights["items"][0]["insight_id"]},
    filters={"date_resolution": "day", "location_resolution": "us"},
    events=[{"event_id": event["event_id"], "representation": "entityeventp"}],
)

price = client.explorer.check_framework_price(framework)
order = client.explorer.buy_frameworks(order=[framework])
data = client.explorer.get_framework_data(framework_id=order["frameworks"][0])

Setup

Overview

Ontology — discover events (client.ontology)

List event types — get_event_types

List event categories — get_event_categories

Search / list events — get_events

Find entities for an event — get_entities

Find insights for an event — get_insights

Builder — event-based frameworks (client.explorer)

Build a framework — build_framework

Collect filters — collect_framework_filters

Filter options — collect_framework_filter_options

Check price — check_framework_price

Purchase — buy_frameworks

Retrieve data — get_framework_data