Block for Devs

Block delivers Carbon Arc data at row-level granularity for large-scale analysis. The client.block namespace lets you discover Block datasets, request trial access, track the approval lifecycle, and manage the S3 ARNs used to consume delivered data — all from the SDK.

Access Requirements

Block is an enterprise add-on. Both of the following must be true before any client.block.* call will succeed:

Your organization must be an enterprise client with Block access. Block is not enabled by default. To add it to your contract, contact support@carbonarc.co.
Your API token must belong to a user who holds a Block role — either Block User or Block Admin. Tokens for users without a Block role cannot call the Block API.

If either condition is not met, Block calls return an authorization error. Reach out to support@carbonarc.co to enable Block or to have a Block role assigned to your user.

Initializing the Client

Block uses the same client as the rest of the SDK — just authenticate with your API token:

from carbonarc import CarbonArcClient

client = CarbonArcClient(token="YOUR_API_TOKEN")

tip

See API Authentication for how to generate and securely store your API token.

Key Concepts

Concept	Description
SKU	A purchasable Block variant identified by `(dataset_id, cut, lag)`. A dataset can expose several cuts, and each cut several lags.
Cut	A slice/configuration of a dataset (e.g. a specific panel or geography).
Lag	The data delay for a SKU (e.g. `"6m"`). Requests pass the lag literal; responses normalize it to integer `lag_days`.
Request status	Per `(cut, lag)` access state: `NONE`, `PENDING`, `APPROVED`, `TRIAL_ACTIVE`, `CONTRACTED`, or `DENIED`.
Delivery	Once access is approved, data is consumed via Polaris (Iceberg REST Catalog) or Amazon S3. See Block Data Delivery.

API Reference

Block API

Complete reference for the client.block namespace — discover datasets, request trial access, track the request lifecycle, and manage S3 ARNs and Polaris credentials.

Available Methods

Discovery

Method	Description
`client.block.list_datasets()`	List all Block datasets visible to your client, with per-cut pricing, lags, and request statuses
`client.block.my_access()`	Datasets you have active access to (approved, trial active, or contracted)
`client.block.pending()`	Datasets with an in-flight (pending) request
`client.block.available()`	Datasets you are eligible to request
`client.block.coming_soon()`	Announced datasets not yet released (preview only)
`client.block.rejected()`	Datasets with a denied request
`client.block.dataset_status(dataset_id)`	One-call summary: catalog metadata + full request history for a dataset
`client.block.request_history(dataset_id)`	Per-request timeline of events for a dataset

Trial-Access Lifecycle

Method	Description
`client.block.request_trial(dataset_id, ...)`	Submit a trial-access request for a dataset
`client.block.list_requests()`	List all Block requests filed by your client
`client.block.get_request(request_id)`	Fetch a single request by ID

Pre-Approvals

Method	Description
`client.block.list_preapprovals()`	List dataset IDs preapproved for your client

S3 ARN Management

Method	Description
`client.block.register_sample_arns(arns)`	Register sample-scoped IAM ARN(s)
`client.block.register_block_arns(arns, dataset_id, ...)`	Register block-scoped IAM ARN(s) for one SKU
`client.block.list_arns()`	List your active registered ARNs
`client.block.bucket_path(dataset_id, ...)`	Get the S3 bucket path for a SKU
`client.block.deregister_arn(arn_id)`	Deregister a previously-registered ARN

Approvals happen in the platform UI

Approving or rejecting requests and pre-approving datasets are not exposed in the SDK. Those decisions are made by Block Admins and Compliance Admins in the platform UI.

Quick Start

from carbonarc import CarbonArcClient

client = CarbonArcClient(token="YOUR_API_TOKEN")

# 1. See what Block datasets you can request
for ds in client.block.available():
    print(ds["dataset_id"], ds.get("label"))

# 2. Request trial access to one
request = client.block.request_trial(
    dataset_id="CA0031",
    lag="6m",
    use_case="Evaluating coverage for a new model.",
)
print("Request submitted:", request["id"])

# 3. Track its status
status = client.block.dataset_status("CA0031")
print(status["requests"])

# 4. Once approved, consume the data via Polaris or S3
#    (see the Block Data Delivery guide)

Typical Workflow

Discover — available() / list_datasets() to find requestable datasets
Request — request_trial() to submit a trial-access request
Track — dataset_status() / request_history() to follow the approval lifecycle
Provision — for S3, register_block_arns() + bucket_path(); for Polaris, use the credentials provided at purchase
Consume — query the delivered data (see Block Data Delivery)

Resource	Description
Block API	Full method reference for `client.block`
Block Data Delivery	Consume delivered Block data via Polaris (Iceberg) or S3
API Authentication	Generate and manage your API token
Python SDK on PyPI	Install the official Carbon Arc package

Need Help?

Email: support@carbonarc.co
GitHub: Carbon Arc Tutorials