Transcripts API — User Guide

Access expert interview transcripts through the Carbon Arc Python SDK. Use the client.transcripts client to browse the transcript catalog, inspect individual transcripts, purchase them, and download the files.

Access is gated by client entitlement. Contact Carbon Arc to enable Transcripts for your account.

Setup

from carbonarc import CarbonArcClient

client = CarbonArcClient(token="your_api_token_here")  # retrieve from your account

All transcript methods are available under client.transcripts.

1. Browse the catalog — `list_transcripts`

Lists the transcripts your account is entitled to browse. Each item includes an is_purchased flag showing whether you already own it. Supports filtering, sorting, and pagination.

# Simple browse
result = client.transcripts.list_transcripts(region="North America")

print(result["total"])   # total matching transcripts
for t in result["transcripts"]:
    print(t["id"], t["title"], t["is_purchased"])

# Filtered + sorted + paginated
# Example only
result = client.transcripts.list_transcripts(
    ticker="AAPL",
    entity=["Apple Inc", "Foxconn"],
    transcript_type="expert_interview",
    region="North America",
    search="supply chain",
    interview_date_from="2024-01-01",
    interview_date_to="2024-12-31",
    is_purchased=False,          # only ones you haven't bought yet
    sort_by="interview_date",    # "published_at" (default) | "title" | "interview_date"
    order="asc",                 # "desc" (default) | "asc"
    page=1,
    size=50,                     # 1–100
)

Parameters (all optional unless noted):

Parameter	Type	Description
`ticker`	`str`	Filter by ticker symbol (entity label).
`entity`	`list[str]`	Filter by one or more entity labels.
`transcript_type`	`str`	Filter by type, e.g. `"expert_interview"`.
`region`	`str`	Filter by region, e.g. `"North America"`.
`search`	`str`	Search in title and description.
`interview_date_from`	`str`	ISO date lower bound, inclusive (`"2024-01-01"`).
`interview_date_to`	`str`	ISO date upper bound, inclusive (`"2024-12-31"`).
`is_purchased`	`bool`	`True` = only purchased; `False` = only not-yet-purchased.
`sort_by`	`str`	`"published_at"` (default), `"title"`, or `"interview_date"`.
`order`	`str`	`"desc"` (default) or `"asc"`.
`page`	`int`	Page number, 1-indexed (default `1`).
`size`	`int`	Page size, 1–100 (default `20`).

Returns: dict with transcripts (list), total (int), page (int), size (int).

2. Inspect a transcript — `get_transcript`

Returns full metadata for a single transcript, including ontology entity tags, a has_pdf flag (whether a PDF version exists), and is_purchased.

detail = client.transcripts.get_transcript("some-uuid")

print(detail["title"])
print("PDF available:", detail["has_pdf"])
print("Purchased:", detail["is_purchased"])

Returns: dict with transcript metadata plus has_pdf and is_purchased.

3. Purchase a transcript — `purchase_transcript`

Purchases a transcript, deducting tokens from your balance.

purchase = client.transcripts.purchase_transcript("some-uuid")
print(purchase["status"], purchase["price"])

Returns: dict with purchase details (id, transcript_id, price, status, created_at).

Errors:

402 — insufficient token balance.
409 — already purchased.

4. Download a transcript — `download_transcript`

Returns a presigned download URL for a transcript you have purchased. The URL expires in 15 minutes, and the download is recorded for audit purposes.

download = client.transcripts.download_transcript("some-uuid", fmt="pdf")  # "txt" | "pdf"

print(download["url"])          # presigned S3 URL
print(download["expires_in"])   # seconds until the URL expires
print(download["format"])

Fetch the file bytes from the returned URL, for example:

import requests

download = client.transcripts.download_transcript("some-uuid", fmt="pdf")
resp = requests.get(download["url"])
with open("transcript.pdf", "wb") as f:
    f.write(resp.content)

Parameters:

Parameter	Type	Description
`transcript_id`	`str`	UUID of the purchased transcript.
`fmt`	`str`	File format — `"txt"` (default) or `"pdf"`.

Returns: dict with url (presigned S3 URL), expires_in (seconds), and format.

Method reference

Method	Returns	Description
`list_transcripts(...)`	`dict`	Browse the catalog with filters, sorting, and pagination.
`get_transcript(transcript_id)`	`dict`	Metadata for a single transcript.
`purchase_transcript(transcript_id)`	`dict`	Purchase a transcript (deducts tokens).
`download_transcript(transcript_id, fmt="txt")`	`dict`	Presigned download URL for a purchased transcript.

Implemented in src/carbonarc/transcripts.py.

End-to-end example

from carbonarc import CarbonArcClient

client = CarbonArcClient(token="your_api_token_here")

# 1. Find a transcript
result = client.transcripts.list_transcripts(search="semiconductors", region="North America")
transcript_id = result["transcripts"][0]["id"]

# 2. Inspect it
detail = client.transcripts.get_transcript(transcript_id)

# 3. Purchase if not already owned
if not detail["is_purchased"]:
    client.transcripts.purchase_transcript(transcript_id)

# 4. Download
download = client.transcripts.download_transcript(transcript_id, fmt="pdf")
print("Download URL (expires in %ss):" % download["expires_in"], download["url"])

Setup

1. Browse the catalog — list_transcripts

2. Inspect a transcript — get_transcript

3. Purchase a transcript — purchase_transcript

4. Download a transcript — download_transcript