Skip to main content
Bigspin is built around a small set of concepts that work together. Understanding them makes everything else in the product — and in these docs — much easier to follow. This page defines each concept and explains how they relate to one another.
A project is the top-level container in Bigspin. It groups a set of transcripts together with all the analysis that runs on them.You can have as many projects as you need — one per product, one per team, one per experiment.Every project shows you how many transcripts it contains and when they were last synced, so you always know how fresh your analysis is.
A transcript is a single recorded AI conversation. It contains one or more turns — individual messages exchanged between participants.Each turn has a role that identifies who sent the message:
RoleDescription
userThe end user interacting with the AI
assistantThe AI’s response
human_agentA human support agent who joined the conversation
systemA system-level instruction or context message
toolOutput from a tool or function call
Transcripts are the raw material for everything Bigspin does. The more transcripts you add to a project, the more reliable and comprehensive your reports become.
A report is the AI-generated analysis Bigspin produces after processing a project’s transcripts. Reports surface:
  • Patterns — Recurring topics and themes across your conversations.
  • Issues — Areas where your AI’s responses fall short of expectations.
  • Trends — How quality and topic distribution change over time.
Reports are designed to be read by domain experts, not just engineers. The findings are expressed in plain language so that product managers, quality leads, and subject matter experts can act on them directly.Bigspin runs analysis automatically whenever new transcripts are added to a project, so your reports stay current as your data grows.
A data source is how transcripts get into a project. Bigspin supports two approaches:File uploads — Upload CSV, TSV, JSON, JSONL, or Parquet files directly from the project creation modal or the project view. Each file can be up to 500 MB.Integrations — Connect a third-party tracing tool so transcripts sync automatically:
  • LangSmith — Connect your LangSmith workspace to stream traces into Bigspin without manual exports.
  • Braintrust — Connect your Braintrust account for continuous ingestion.
When you configure an integration, you can also apply transcript filters — metadata-based criteria that limit which traces get pulled into a given project. This lets you create focused projects (for example, only traces tagged with a specific environment or model version) without exporting separate files.See Integrations for setup instructions.
An API key is a credential that authenticates programmatic requests to the Bigspin API. You need an API key to:
  • Create projects and upload transcripts via the Projects and Transcripts APIs.
  • Read project and transcript data programmatically.
You generate and manage API keys from Settings → API Keys in the dashboard. Treat your API keys like passwords — do not commit them to source control or share them publicly.
Bigspin does not display a key’s secret value after initial creation. Copy it immediately and store it somewhere safe, such as a secrets manager or environment variable.

​
How the concepts fit together

A typical Bigspin workflow connects all of these concepts in sequence:
  1. You create a project.
  2. You add transcripts via file upload, a data source integration, or the Transcripts API.
  3. Bigspin analyzes the transcripts and generates a report.
  4. You act on the report’s findings — refining prompts, updating training data, or adjusting your AI’s behavior.
  5. New transcripts flow in, a fresh report runs, and the cycle repeats.

Quickstart

Follow the step-by-step guide to create your first project and report.

API Reference

Explore the Projects and Transcripts APIs to push data into Bigspin programmatically.