GraphQL Queries

GraphQL allows you to request exactly the data you need from BuildBetter. These queries help you fetch calls, signals, documents, and more.

Authentication

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

X-BuildBetter-Api-Key: YOUR_ORGANIZATION_API_KEY

Endpoint

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

Query Examples

Get Recent Calls

Fetch a list of recent calls with participants

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

Get Call Signals

Retrieve signals (key moments) from a specific call

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:

{
  "callId": 12345
}

Use cases:

Creating call analysis dashboards
Extracting key insights
Building signal-based reports

Get Call Transcript

Retrieve the full transcript for a call

query GetCallTranscript($callId: bigint!) {
  interview_by_pk(id: $callId) {
    id
    name
    started_at
    duration_sec
    transcript_segments {
      text
      start_sec
      end_sec
      attendee {
        person {
          first_name
          last_name
        }
      }
    }
  }
}

Use cases:

Building transcript viewers
Creating searchable interfaces
Generating custom summaries

Get Document Details

Retrieve AI-generated documents with source calls

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

Search Calls

Search for calls by various criteria

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

Get People

Retrieve people/contacts from your workspace

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

Pagination

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

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:

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

Best Practices

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

Getting Started

GraphQL API

REST API

Webhooks

Reference

Authentication

Endpoint

Query Examples

Filtering

Best Practices

Getting Started

GraphQL API

REST API

Webhooks

Reference

​Authentication

​Endpoint

​Query Examples

​Pagination

​Filtering

​Best Practices

Authentication

Endpoint

Query Examples

Pagination

Filtering

Best Practices