Skip to main content
Using TypeScript? Check out our GraphQL SDK for a fully typed client.
We provide a number of methods for fetching threads:
  1. Get a thread by ID
  2. Get a thread by external ID
  3. List threads — paginated, with filters
  4. Search threads — full-text search on title, description and message contents
All of these endpoints require the following permissions:
  • thread:read

​
Get a thread by ID

Query
query getThread($threadId: ID!) {
  thread(threadId: $threadId) {
    id
    ref
    externalId
    title
    description
    previewText
    priority
    status
    statusChangedAt {
      iso8601
    }
    customer {
      id
      fullName
      email {
        email
      }
    }
    assignedTo {
      __typename
      ... on User {
        id
        fullName
      }
      ... on MachineUser {
        id
        fullName
      }
    }
    labels {
      id
      labelType {
        id
        name
      }
    }
  }
}
Variables
{
  "threadId": "th_01H8H46YPB2S4MAJM382FG9423"
}

​
Get a thread by external ID

A thread’s externalId is unique within a customer, which is why the customer ID is required when looking up by external ID.
Query
query getThreadByExternalId($customerId: ID!, $externalId: ID!) {
  threadByExternalId(customerId: $customerId, externalId: $externalId) {
    id
    ref
    externalId
    title
    status
  }
}
Variables
{
  "customerId": "c_01H14DFQ4PDYBH398J1E99TWSS",
  "externalId": "ticket-12345"
}

​
List threads

The threads query supports rich filtering (status, status detail, assignee, customer, labels, priority, date ranges) and sorting. This is the right query for building inbox-style views.
Query
query listThreads(
  $filters: ThreadsFilter
  $first: Int = 25
  $after: String
) {
  threads(filters: $filters, first: $first, after: $after, sortBy: { field: CREATED_AT, direction: DESC }) {
    edges {
      node {
        id
        ref
        title
        status
        priority
        customer {
          id
          fullName
        }
        labels {
          labelType {
            id
            name
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
Variables
{
  "filters": {
    "statuses": ["TODO", "SNOOZED"],
    "isAssigned": false
  },
  "first": 25
}

​
Search threads

searchThreads performs a full-text search across thread title, description and message contents. For exact lookups prefer thread or threadByExternalId.
Query
query searchThreads($term: String!, $first: Int = 25, $after: String) {
  searchThreads(searchQuery: { term: $term }, first: $first, after: $after) {
    edges {
      node {
        thread {
          id
          ref
          title
          status
          customer {
            id
            fullName
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
Variables
{
  "term": "refund",
  "first": 25
}