Skip to main content
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

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
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
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
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 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
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

  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