Learn the fundamentals of constructing GraphQL queries to retrieve specific data from the BuildBetter API.
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:
name
and started_at
of the first call (more on the interview
type below). The result will contain those fields.
$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.
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 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.