​
Building GraphQL Queries

GraphQL queries allow you to specify exactly what data you need, and the response will mirror the structure of your request. Here are some key aspects of building queries:
  • Structure: A basic GraphQL query uses the syntax query { ... } (or mutation { ... } for mutations). Inside, you list the fields you want to retrieve, and you can nest related fields. The response JSON will have the same shape as the fields you asked for. For example, to get a call’s name and start time, you might write: 
    query {
  interview(limit: 1) {
    name
    started_at
  }
}
    This query asks for the name and started_at of the first call (more on the interview type below). The result will contain those fields.
  • Variables: Instead of hard-coding values in your queries (like IDs or filters), GraphQL variables let you write flexible queries. You define variables in the query signature, and provide their values separately in the request. For example, a query that fetches a specific call by ID using a variable: 
    query GetCallById($callId: bigint!) {
  interview(where: { id: { _eq: $callId } }) {
    id
    name
    started_at
  }
}
    In this query, $callId is a variable of type bigint! (an ID type used for calls). The where filter uses _eq (equals) to match the call ID. When you send this query, you’d include a JSON variables payload such as: { "callId": 12345 }. The API will substitute the variable and return the matching call. You can use variables for any dynamic value (IDs, search keywords, filters, etc.), which makes your queries reusable and safer.
  • Filtering and Ordering: The API supports rich filtering on query fields. Inside a where clause, you can use operators like _eq (equals), _neq (not equals), _in, _ilike (case-insensitive pattern match), and many others. These correspond to SQL-like filters. For example, to filter documents by status you might use where: { status: { _eq: "completed" } }. You can also sort results using an order_by argument on query fields. For example, order_by: { created_at: desc } will sort results by creation time in descending order. Pagination can be handled with limit/offset arguments – e.g., limit: 10, offset: 0 to get the first 10 results, then adjust offset for the next page.
  • Schema Introspection: The GraphQL schema defines all available types, fields, and operations. You can introspect the schema (for example, using GraphiQL or Apollo Sandbox if provided, or by sending the special __schema introspection query) to see the exact fields and types. Key types you’ll be interacting with include interview (calls), extraction (signals), and document. We’ll explain these in the Data Access section. Each of these types has fields and relationships you can query. For instance, the interview type has relationships for participants, transcripts, etc., and the document type has relationships for its creator and any source calls.
In summary, structure your queries to ask for exactly what you need, use variables to parameterize queries, and apply filters to narrow results. In the next section, we’ll look at the specific data models (calls, signals, documents) and how to retrieve their data via GraphQL.