Skip to main content

Entity Lists

Entity Lists are reusable collections of entities companies, brands, locations, people, or any other ontology-backed representation that define what a user wants to analyze. Instead of passing entities one by one, users can reference a stable, named, versioned object across the Carbon Arc SDK and APIs.

Entity selection shows up everywhere in the platform: Framework purchases, extracts, recurring jobs, alerts, and saved workflows. This section of the docs contains pre-built entity sets to choose from.

Example:

# Option 1: Define specific entity sets (example with company entities)
entity_sets = [
    {"carc_id": 64781, "representation": "company"}, # Walmart Inc
    {"carc_id": 64702, "representation": "company"}, # Target
    {"carc_id": 64127, "representation": "company"}, # Amazon
    {"carc_id": 64152, "representation": "company"}, # Best Buy
    {"carc_id": 58072, "representation": "company"}, # Trader Joes

    # Add more entities as needed
]

What an Entity List Contains​

Each entry includes:

  • carc_id — the canonical Carbon Arc ID
  • representation — company, brand, location, etc.
  • Optional metadata: name, version, tags, notes

Core Use Cases​

  1. Builder / Frameworks Entity Lists power entity–insight pairing and let users save common sets (“Competitors,” “QSR Brands in CA/TX/FL,” etc.).

  2. API + SDK Reference an entity_list_id instead of long arrays of IDs—cleaner, consistent, and versioned.

  3. Recurring Jobs Jobs can run daily/weekly without redefining entities (“Daily POS panel for 80 brands,” “Weekly card spend for 12 companies”).