Data Retrieval - Claims

This guide demonstrates how to set up your environment, build a framework, estimate and place an order, and then retrieve the results using the Carbon Arc Python SDK. The below is an example showing how to return Walmart Credit Card Spend from our Card - US Detailed Panel dataset.

Setup Your Environment

# Import required dependencies
import os
from dotenv import load_dotenv
from carbonarc import CarbonArcClient

load_dotenv()

## Read in environment variables
API_AUTH_TOKEN=os.getenv("API_AUTH_TOKEN")

# Create API Client
client = CarbonArcClient(API_AUTH_TOKEN)

print('Client initialized successfully')

Build A Claims Framework

Build a framework for Endeavor Health (Company ID 70373), retrieving Claim Counts

framework = client.explorer.build_framework(
    entities=[{"carc_id": 70373, "representation": "company"}],
    insight=596,  # Insight ID for "Claim Counts"
    filters={
        "location_resolution": "us",
        "date_resolution": "day",
        "date_range": {
            "start_date": "2022-06-20",
            "end_date": "2025-06-19"
        }
    },
    aggregate="sum"
)
print("Framework built successfully.")

Discover available filters and their values

filters = client.explorer.collect_framework_filters(framework)
filter_options = client.explorer.collect_framework_filter_options(framework, filter_key="platform")

Estimate pricing and place your order

price = client.explorer.check_framework_price(framework)
print("Estimated cost:", price)

order = client.explorer.buy_frameworks([framework])
print("Order details:", order)

Retrieve framework metadata

framework_id = "INSERT_YOUR_FRAMEWORK_ID_HERE"
metadata = client.explorer.get_framework_metadata(framework_id)

Retrieve full dataset

data = client.explorer.get_framework_data(framework_id)

Paginate results (optional if data is large)

page_data = client.explorer.get_framework_data(
    framework_id=framework_id,
    page=1,
    size=100
)
print(f"Retrieved {len(page_data)} records")