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

# Legacy GraphQL Queries

> Legacy GraphQL query examples for integrations migrating to the BuildBetter REST API.

The BuildBetter GraphQL API is being deprecated for customer integrations. Use the REST API for new work and migrate existing GraphQL integrations to REST.

<Warning>
  GraphQL examples on this page are legacy migration reference. Move recording and transcript reads to the [Recordings API](/pages/api/recordings).
</Warning>

## Authentication

Legacy GraphQL queries require authentication. Include your API key in the request header:

```bash theme={null}
X-BuildBetter-Api-Key: YOUR_ORGANIZATION_API_KEY
```

## Endpoint

```
POST https://api.buildbetter.app/graphql
```

## Query Examples

<AccordionGroup>
  <Accordion title="Get Recent Calls">
    **Fetch a list of recent calls with participants**

    ```graphql theme={null}
    query GetRecentCalls {
      interview(limit: 5, order_by: { started_at: desc }) {
        id
        name
        started_at
        type {
          name
        }
        attendees {
          person {
            first_name
            last_name
            email
          }
        }
      }
    }
    ```

    **Use cases:**

    * Building dashboards with recent activity
    * Displaying call history
    * Getting participant lists for follow-ups
  </Accordion>

  <Accordion title="Get Call Signals">
    **Retrieve signals (key moments) from a specific call**

    ```graphql theme={null}
    query GetSignalsForCall($callId: bigint!) {
      extraction(
        where: { interview_id: { _eq: $callId } }
        order_by: { start_sec: asc }
      ) {
        id
        summary
        context
        start_sec
        end_sec
        types {
          type {
            name
          }
        }
        topics {
          topic {
            text
          }
        }
        attendee {
          person {
            first_name
            last_name
          }
        }
      }
    }
    ```

    **Variables:**

    ```json theme={null}
    {
      "callId": 12345
    }
    ```

    **Use cases:**

    * Creating call analysis dashboards
    * Extracting key insights
    * Building signal-based reports
  </Accordion>

  <Accordion title="Get Call Transcript">
    **Retrieve the full transcript for a call**

    <Warning>
      The GraphQL API is being deprecated for customer integrations, and GraphQL `interview.monologues` is deprecated as of Wednesday, July 1, 2026. Move transcript reads to the REST transcript endpoint. During migration, use sentence-backed transcript relationships such as `sentences` or `transcript_segments`.
    </Warning>

    ```graphql theme={null}
    query GetCallTranscript($callId: bigint!) {
      interview_by_pk(id: $callId) {
        id
        name
        started_at
        duration_sec
        sentences(order_by: { start_sec: asc }) {
          text
          start_sec
          end_sec
          speaker
        }
      }
    }
    ```

    **Use cases:**

    * Building transcript viewers
    * Creating searchable interfaces
    * Generating custom summaries
  </Accordion>

  <Accordion title="Get Document Details">
    **Retrieve AI-generated documents with source calls**

    ```graphql theme={null}
    query GetDocument($docId: bigint!) {
      document_by_pk(id: $docId) {
        id
        name
        status
        content
        created_at
        creator {
          person {
            first_name
            last_name
          }
        }
        input_data {
          call {
            id
            name
            started_at
          }
        }
      }
    }
    ```

    **Use cases:**

    * Displaying AI summaries
    * Showing document history
    * Tracking document status
  </Accordion>

  <Accordion title="Search Calls">
    **Search for calls by various criteria**

    ```graphql theme={null}
    query SearchCalls(
      $searchTerm: String!
      $startDate: timestamptz
      $endDate: timestamptz
    ) {
      interview(
        where: {
          _and: [
            { name: { _ilike: $searchTerm } }
            { started_at: { _gte: $startDate } }
            { started_at: { _lte: $endDate } }
          ]
        }
        order_by: { started_at: desc }
      ) {
        id
        name
        started_at
        attendees {
          person {
            first_name
            last_name
            email
          }
        }
      }
    }
    ```

    **Use cases:**

    * Implementing search functionality
    * Building filtered call lists
    * Creating date-based reports
  </Accordion>

  <Accordion title="Get People">
    **Retrieve people/contacts from your workspace**

    ```graphql theme={null}
    query GetPeople($limit: Int = 10) {
      person(limit: $limit, order_by: { created_at: desc }) {
        id
        first_name
        last_name
        email
        company {
          name
          domain
        }
        attendances {
          interview {
            id
            name
            started_at
          }
        }
      }
    }
    ```

    **Use cases:**

    * Building contact directories
    * Tracking participant history
    * Managing customer relationships
  </Accordion>
</AccordionGroup>

## Pagination

For large result sets, use pagination with `limit` and `offset`:

```graphql theme={null}
query GetCallsPaginated($limit: Int!, $offset: Int!) {
  interview(
    limit: $limit
    offset: $offset
    order_by: { started_at: desc }
  ) {
    id
    name
    started_at
  }
}
```

## Filtering

Use the `where` clause to filter results:

```graphql theme={null}
query FilteredCalls {
  interview(
    where: {
      _and: [
        { started_at: { _gte: "2025-01-01" } }
        { attendees: { person: { email: { _eq: "john@example.com" } } } }
      ]
    }
  ) {
    id
    name
  }
}
```

## Best Practices

1. **Request only needed fields** - GraphQL returns only what you ask for
2. **Use variables** - Makes queries reusable and secure
3. **Implement pagination** - For large datasets
4. **Handle errors gracefully** - Check for errors in responses
5. **Cache results** - When appropriate for your use case