Practical implementation examples for common GraphQL API use cases.

​
Getting Recent Calls

Retrieve the most recent calls from your workspace with participant information. 
query GetRecentCalls {
  interview(limit: 5, order_by: { started_at: desc }) {
    id
    name
    started_at
    duration_sec
    type {
      name
    }
    attendees {
      person {
        first_name
        last_name
        email
      }
    }
  }
}

​
Extracting Call Insights

Get signals and key moments from a specific call. 
query GetCallInsights($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
      }
    }
  }
}

​
Building a Call Dashboard

Create a comprehensive dashboard showing calls, participants, and key metrics. 
query DashboardData($startDate: timestamptz!, $endDate: timestamptz!) {
  # Get calls in date range
  calls: interview(
    where: {
      started_at: { _gte: $startDate, _lte: $endDate }
    }
    order_by: { started_at: desc }
  ) {
    id
    name
    started_at
    duration_sec
    attendee_count: attendees_aggregate {
      aggregate {
        count
      }
    }
    signal_count: extractions_aggregate {
      aggregate {
        count
      }
    }
  }
  
  # Get top participants
  participants: person(
    limit: 10
    order_by: { attendances_aggregate: { count: desc } }
  ) {
    first_name
    last_name
    email
    call_count: attendances_aggregate {
      aggregate {
        count
      }
    }
  }
  
  # Get signal statistics
  signals: extraction_aggregate(
    where: {
      interview: {
        started_at: { _gte: $startDate, _lte: $endDate }
      }
    }
  ) {
    aggregate {
      count
    }
  }
}

​
Searching and Filtering

Find specific calls or content across your workspace. 
query SearchCalls(
  $searchTerm: String!
  $participantEmail: String
  $startDate: timestamptz
  $endDate: timestamptz
) {
  interview(
    where: {
      _and: [
        { name: { _ilike: $searchTerm } }
        { started_at: { _gte: $startDate } }
        { started_at: { _lte: $endDate } }
        {
          attendees: {
            person: {
              email: { _eq: $participantEmail }
            }
          }
        }
      ]
    }
    order_by: { started_at: desc }
  ) {
    id
    name
    started_at
    attendees {
      person {
        first_name
        last_name
        email
      }
    }
  }
}

​
Document Generation Status

Monitor AI-generated document creation and status. 
query GetDocumentStatus($docId: bigint!) {
  document_by_pk(id: $docId) {
    id
    name
    status
    content
    created_at
    updated_at
    creator {
      person {
        first_name
        last_name
      }
    }
    # Source calls used to generate this document
    input_data {
      call {
        id
        name
        started_at
      }
    }
  }
}

​
Pagination Patterns

Handle large datasets efficiently with cursor-based or offset pagination. 
query GetCallsPaginated($limit: Int!, $offset: Int!) {
  interview(
    limit: $limit
    offset: $offset
    order_by: { started_at: desc }
  ) {
    id
    name
    started_at
  }
  
  # Get total count for pagination controls
  interview_aggregate {
    aggregate {
      count
    }
  }
}

​
Error Handling

Properly handle errors and edge cases in your GraphQL implementations. 
async function safeGraphQLQuery(query, variables = {}) {
  try {
    const response = await fetch('https://api.buildbetter.app/graphql', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ query, variables })
    });
    
    const result = await response.json();
    
    // Check for GraphQL errors
    if (result.errors) {
      console.error('GraphQL Errors:', result.errors);
      
      // Handle specific error types
      result.errors.forEach(error => {
        if (error.message.includes('permission denied')) {
          throw new Error('Access denied. Check your API key permissions.');
        }
        if (error.message.includes('not found')) {
          throw new Error('Resource not found.');
        }
      });
      
      throw new Error('GraphQL query failed');
    }
    
    return result.data;
    
  } catch (error) {
    // Handle network errors
    if (error.name === 'NetworkError') {
      console.error('Network error:', error);
      throw new Error('Unable to connect to API');
    }
    
    // Re-throw other errors
    throw error;
  }
}

​
Tips

  • Request only needed fields - GraphQL returns exactly what you ask for
  • Use pagination for large datasets to avoid timeouts
  • Store API keys securely - never expose them in client-side code
  • Test queries first in a GraphQL playground before implementing

​
Next Steps

GraphQL API Reference

Explore the complete GraphQL API reference documentation

Authentication Setup

Learn how to authenticate your API requests