Block API

The client.block namespace provides programmatic access to Carbon Arc Block — row-level data delivered via Polaris (Iceberg) or Amazon S3. Use it to discover Block datasets, request trial access, track the approval lifecycle, and manage the S3 ARNs used to consume delivered data.

Access Requirements

Block is an enterprise add-on. Every client.block.* call requires both:

An organization that is an enterprise client with Block access — contact support@carbonarc.co to enable it.
An API token belonging to a user with a Block role (Block User or Block Admin).

Calls from clients without Block access, or from tokens whose user has no Block role, return an authorization error.

Quick Start

from carbonarc import CarbonArcClient

client = CarbonArcClient(token="YOUR_API_TOKEN")

datasets = client.block.list_datasets()

Discovery

List All Datasets

List every Block dataset visible to your client, with per-cut pricing, available lags, and per-(cut, lag) request statuses inline.

response = client.block.list_datasets()

for ds in response.get("datasets", []):
    print(ds["dataset_id"], ds.get("label"), ds.get("status"))

Response Structure

{
  "datasets": [
    {
      "dataset_id": "CA0031",
      "label": "Example Block Dataset",
      "vendor": "Example Vendor",
      "description": "Row-level data for ...",
      "status": "ready",
      "compliance_tear_sheet": { "download_url": "https://app.carbonarc.ai/api/v1/block/datasets/CA0031/compliance-tear-sheet" },
      "cuts": [
        {
          "cut": "core",
          "lags": ["6m", "1y"],
          "annual_price": "...",
          "request_statuses": { "6m": "APPROVED", "1y": "NONE" }
        }
      ]
    }
  ]
}

When a dataset has a compliance tear sheet, its entry carries a compliance_tear_sheet object whose download_url is an absolute link you can fetch directly. Each request_statuses value is one of:

Status	Meaning
`NONE`	No request on this `(cut, lag)`
`PENDING`	A request is in flight
`APPROVED`	Access approved
`TRIAL_ACTIVE`	A trial is currently active
`CONTRACTED`	Access is under contract
`DENIED`	A request was denied

Dataset status is typically ready (requestable) or coming_soon (preview only — visible with metadata and pricing, but not yet requestable).

Filtered Discovery Helpers

These helpers filter list_datasets() into common views so you don't have to inspect statuses yourself.

client.block.my_access()    # datasets you have active access to (APPROVED / TRIAL_ACTIVE / CONTRACTED)
client.block.pending()      # datasets with an in-flight (PENDING) request
client.block.available()    # 'ready' datasets you can request (no active/pending/denied status)
client.block.coming_soon()  # announced datasets not yet released (preview only)
client.block.rejected()     # datasets with a DENIED request

Each returns a list of dataset entries in the same shape as list_datasets().

# Example: list everything you're eligible to request
for ds in client.block.available():
    print(ds["dataset_id"], ds.get("label"))

Dataset Status

Get a one-call summary of your access for a single dataset. Joins catalog metadata (current per-cut / per-lag statuses) with your full historical request timeline against that dataset.

status = client.block.dataset_status(dataset_id="CA0031")

Parameter	Type	Required	Description
`dataset_id`	string	Yes	CA-prefixed dataset identifier (e.g. `"CA0031"`). Matched exactly — case-sensitive.

Response Structure

{
  "dataset_id": "CA0031",
  "catalog": {
    "label": "Example Block Dataset",
    "vendor": "Example Vendor",
    "description": "...",
    "status": "ready",
    "lag_days": 180,
    "compliance_tear_sheet": { "download_url": "https://app.carbonarc.ai/api/v1/block/datasets/CA0031/compliance-tear-sheet" },
    "cuts": [
      {
        "cut": "core",
        "skus": [
          {
            "lag_days": 180,
            "request_status": "APPROVED",
            "arns": [ { "arn": "arn:aws:iam::...", "id": "..." } ]
          }
        ]
      }
    ]
  },
  "requests": [
    {
      "id": "…",
      "status": "pending_block_admin",
      "lag_days": 180,
      "cut": "core",
      "internal_queue_step": "pending",
      "requestor_email": "you@example.com",
      "created_at": "2026-06-01T12:00:00"
    }
  ]
}

catalog is null if the dataset is not visible to your client, and requests is an empty list if you've never filed a request against it. Lags are normalized to integer lag_days. internal_queue_step collapses Carbon Arc's internal review queue to a customer-facing pending / approved / rejected / null.

Request History

Get a per-request timeline of every Block request your client has filed against a dataset, whether approved, in-flight, denied, or contracted.

history = client.block.request_history(dataset_id="CA0031")

for req in history:
    print(req["request_id"], req["current_status"])
    for event in req["events"]:
        print("  ", event["step"], event.get("at"))

Parameter	Type	Required	Description
`dataset_id`	string	Yes	CA-prefixed dataset identifier. Matched exactly — case-sensitive.

Each request carries an ordered events list. A step is only emitted once its underlying data exists:

Step	Description
`submitted`	Request created (`actor` = requestor email, `at`, `use_case`)
`block_admin_approved`	Approved by a Block Admin
`compliance_approved`	Approved by Compliance
`fully_approved`	Fully approved (`at` = approval time)
`rejected`	Rejected (`actor`, `source`, `reason`, `at`)
`cancellation_requested`	Cancellation requested (`actor`, `at`, `reason`)
`trial_started`	Trial began (`at`, `trigger`)
`first_ingestion`	First data ingestion (`at`)
`trial_ends`	Trial end date (`at`)

Returns an empty list if your client has never filed a request against the dataset.

Trial-Access Lifecycle

Request Trial Access

Submit a Block trial-access request for a dataset.

request = client.block.request_trial(
    dataset_id="CA0031",
    lag="6m",
    cut="core",
    use_case="Evaluating coverage for a new forecasting model.",
)

print("Request ID:", request["id"])

Parameter	Type	Required	Description
`dataset_id`	string	Yes	CA-prefixed dataset identifier (e.g. `"CA0031"`)
`lag`	string	No	Lag variant for the SKU (e.g. `"6m"`)
`cut`	string	No	Cut variant for the SKU
`use_case`	string	No	Rationale shown to reviewers
`additional_email_recipients`	list[str]	No	Extra addresses to copy on workflow notifications
`accepted_block_tou_version_id`	string	No	UUID of the per-dataset Block Terms of Use version the requestor accepted. Required when a dataset-specific TOU exists.

Returns a dict describing the created request (id, status, dataset_id, …).

List Requests

List all Block requests filed by your client.

response = client.block.list_requests()

print("Total:", response.get("total"))
for req in response.get("requests", []):
    print(req["id"], req["dataset_id"], req["status"])

The response includes requests (the request rows), total, and users_by_email (a lookup table of requestor / approver details). When a dataset has a compliance tear sheet, each request row carries a compliance_tear_sheet object whose download_url is an absolute link you can pass straight to a browser or HTTP client.

Get a Single Request

request = client.block.get_request(request_id="…")

Parameter	Type	Required	Description
`request_id`	string	Yes	The request's UUID

note

Approving or rejecting requests is intentionally not available in the SDK — those decisions go through the platform UI, where the Block Admin / Compliance Admin workflow lives.

Pre-Approvals

List the dataset IDs preapproved for your client. Preapproved datasets skip the per-request compliance step.

response = client.block.list_preapprovals()

for dataset_id in response.get("items", []):
    print(dataset_id)

note

Pre-approving or un-pre-approving a dataset is a Compliance Admin decision made in the platform UI, and is not exposed in the SDK.

S3 ARN Management

If you consume Block data via Amazon S3, register the AWS IAM principal(s) (ARNs) that should be granted read access. See Block Data Delivery for the full S3 delivery model.

Register Sample ARNs

client.block.register_sample_arns(
    arns=["arn:aws:iam::123456789012:user/analyst"]
)

Register Block ARNs

client.block.register_block_arns(
    arns=["arn:aws:iam::123456789012:user/analyst"],
    dataset_id="CA0031",
    lag="6m",
    cut="core",
)

Parameter	Type	Required	Description
`arns`	list[str]	Yes	IAM ARN(s) to register
`dataset_id`	string	Yes	The dataset whose SKU bucket to grant access to
`lag`	string	No	Lag variant of the SKU
`cut`	string	No	Cut variant of the SKU

List Registered ARNs

response = client.block.list_arns()

for arn in response.get("items", []):
    print(arn)

Returns your active registered ARNs across both sample and block scopes.

Get Bucket Path

Get the S3 bucket path for a given SKU.

path = client.block.bucket_path(
    dataset_id="CA0031",
    lag="6m",
    cut="core",
    catalog="bulk",   # "bulk" (default, exact SKU match) or "sample" (lag-agnostic)
)

Parameter	Type	Required	Description
`dataset_id`	string	Yes	The dataset identifier
`lag`	string	No	Lag variant of the SKU
`cut`	string	No	Cut variant of the SKU
`catalog`	string	No	`"bulk"` (default — exact SKU match) or `"sample"` (lag-agnostic)

Deregister an ARN

client.block.deregister_arn(arn_id="…")

Parameter	Type	Required	Description
`arn_id`	string	Yes	The ID of a previously-registered ARN (from `list_arns()`)

Consuming Delivered Data

Once your access is approved, consume the data via Polaris (Iceberg REST Catalog) — the recommended method — or Amazon S3. Polaris client credentials are provided at purchase, and the SDK's ARN methods above manage S3 access. See Block Data Delivery for connecting Snowflake, ClickHouse, and other platforms.

Error Handling

Wrap calls in try/except to handle authorization and connection errors gracefully. A 403-style error usually means your client lacks Block access or your token's user has no Block role (see the Access Requirements note at the top of this page).

try:
    datasets = client.block.list_datasets()
except Exception as e:
    print(f"Block request failed: {e}")

Resource	Description
Block for Devs	Overview, key concepts, and workflow
Block Data Delivery	Consume delivered Block data via Polaris (Iceberg) or S3
API Authentication	Generate and manage your API token

Need Help?

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

Quick Start

Discovery

List All Datasets

Response Structure

Filtered Discovery Helpers

Dataset Status

Response Structure

Request History

Trial-Access Lifecycle

Request Trial Access

List Requests

Get a Single Request

Pre-Approvals

S3 ARN Management

Register Sample ARNs

Register Block ARNs

List Registered ARNs

Get Bucket Path

Deregister an ARN

Consuming Delivered Data

Error Handling

Related Resources

Need Help?