> ## Documentation Index
> Fetch the complete documentation index at: https://next.gentrace.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Pipelines

> Programmatic access to Gentrace pipelines

The pipelines SDK provides programmatic access to Gentrace pipelines. Pipelines are the top-level organizational unit that contains datasets, experiments, and traces.

## Basic usage

<CodeGroup dropdown>
  ```typescript theme={null}
  import { init, pipelines } from 'gentrace';

  init({
    apiKey: process.env.GENTRACE_API_KEY,
  });

  // List pipelines
  const pipelineList = await pipelines.list();

  // Access the pipelines
  for (const pipeline of pipelineList.data) {
    console.log(pipeline.slug);
    console.log(pipeline.displayName);
  }
  ```

  ```python theme={null}
  import os
  from gentrace import init, pipelines

  init(api_key=os.environ["GENTRACE_API_KEY"])

  # List pipelines
  pipeline_list = await pipelines.list()

  # Access the pipelines
  for pipeline in pipeline_list.data:
      print(pipeline.slug)
      print(pipeline.display_name)
  ```
</CodeGroup>

## Overview

The SDK is built by [Stainless](https://stainless.com) and provides type-safe access to Gentrace entities. The `pipelines` object exposes methods to create, retrieve, update, and list pipelines.

## Pipeline structure

Each pipeline contains:

<ResponseField name="id" type="string" required>
  Unique identifier (UUID)
</ResponseField>

<ResponseField name="slug" type="string" required>
  URL-friendly unique identifier
</ResponseField>

<ResponseField name="displayName" type="string">
  Optional human-readable name
</ResponseField>

<ResponseField name="folderId" type="string">
  Optional folder UUID for organization
</ResponseField>

<ResponseField name="goldenDatasetId" type="string">
  UUID of the golden dataset (if set)
</ResponseField>

<ResponseField name="archivedAt" type="string">
  Timestamp when archived (null if active)
</ResponseField>

<ResponseField name="createdAt" type="string" required>
  Creation timestamp
</ResponseField>

<ResponseField name="updatedAt" type="string" required>
  Last update timestamp
</ResponseField>

## Resource methods

### Create a pipeline

<CodeGroup dropdown>
  ```typescript theme={null}
  const pipeline = await pipelines.create({
    slug: 'customer-support-ai',
    displayName: 'Customer Support AI Pipeline',
    folderId: 'folder-uuid', // optional
  });
  ```

  ```python theme={null}
  pipeline = await pipelines.create(
      slug="customer-support-ai",
      display_name="Customer Support AI Pipeline",
      folder_id="folder-uuid",  # optional
  )
  ```
</CodeGroup>

### Retrieve a pipeline

<CodeGroup dropdown>
  ```typescript theme={null}
  const pipeline = await pipelines.retrieve('pipeline-id');
  console.log(pipeline.slug);
  ```

  ```python theme={null}
  pipeline = await pipelines.retrieve("pipeline-id")
  print(pipeline.slug)
  ```
</CodeGroup>

### Update a pipeline

<CodeGroup dropdown>
  ```typescript theme={null}
  const pipeline = await pipelines.update('pipeline-id', {
    displayName: 'Updated Pipeline Name',
    isArchived: false,
  });
  ```

  ```python theme={null}
  pipeline = await pipelines.update(
      "pipeline-id",
      display_name="Updated Pipeline Name",
      is_archived=False,
  )
  ```
</CodeGroup>

### List with filters

<CodeGroup dropdown>
  ```typescript theme={null}
  // Filter by folder or slug
  const pipelineList = await pipelines.list({
    folderId: 'folder-id',
    slug: 'customer-support', // exact match or use advanced filters
  });
  ```

  ```python theme={null}
  # Filter by folder or slug
  pipeline_list = await pipelines.list(
      folder_id="folder-id",
      slug="customer-support",  # exact match
  )
  ```
</CodeGroup>

## Usage in AI workflows

Pipelines are used throughout Gentrace to organize your AI workflows:

<CodeGroup dropdown>
  ```typescript theme={null}
  // Use pipeline ID with interaction()
  const tracedFunction = interaction('My AI Function', myAIFunction, {
    pipelineId: pipeline.id,
  });

  // Use pipeline ID with experiment()
  experiment(pipeline.id, async () => {
    // Your experiment code
  });
  ```

  ```python theme={null}
  # Use pipeline ID with interaction()
  @interaction(pipeline_id=pipeline.id, name="My AI Function")
  async def traced_function():
      # Your AI function code
      pass

  # Use pipeline ID with experiment()
  @experiment(pipeline_id=pipeline.id)
  async def my_experiment():
      # Your experiment code
      pass
  ```
</CodeGroup>

## See also

* [Datasets](./datasets) - Managing datasets within pipelines
* [Experiments](./experiments) - Running experiments on pipelines
* [`interaction()`](../tracing/interactions) - Tracing functions within pipelines
* [`experiment()`](../evaluation/experiments) - Creating experiments for pipelines