Fetch tasks

Fetch tasks by ID, by their short reference, or as a paginated collection.

There are three ways to fetch tasks:

• Get tasks: paginated collection
• Get task by ID
• Get task by ref. ref is the short human-readable identifier shown in the Plain app (e.g. T-123)

For TypeScript, the GraphQL SDK gives you a fully typed client for these operations.

These operations require the following permissions:

• task:read

Get tasks

Query

query getTasks($first: Int = 50, $after: String) {
  tasks(first: $first, after: $after) {
    edges {
      node {
        id
        ref
        title
        description
        status
        priority
        assignedTo {
          __typename
          ... on User {
            id
            fullName
          }
          ... on MachineUser {
            id
            fullName
          }
        }
        company {
          id
          name
        }
        tenant {
          id
          name
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Variables

{
  "first": 50
}

Get task by ID

Query

query getTask($taskId: ID!) {
  task(taskId: $taskId) {
    id
    ref
    title
    description
    status
    priority
    assignedTo {
      __typename
      ... on User {
        id
        fullName
      }
      ... on MachineUser {
        id
        fullName
      }
    }
  }
}

Variables

{
  "taskId": "ta_01HXXXXXXXXXXXXXXXXXXXXXXX"
}

Get task by ref

Query

query getTaskByRef($ref: String!) {
  taskByRef(ref: $ref) {
    id
    ref
    title
    description
    status
    priority
  }
}

Variables

{
  "ref": "T-123"
}

Get the knowledge gap behind a task

When Ari raises a task for a knowledge gap, the task’s sourceLinks holds one entry with sourceType: "knowledge_gap", and on that entry knowledgeGap carries the gap’s title and description. The task’s status is the gap’s status; to change it, update the task.

Knowledge gaps are in beta. sourceLinks and the KnowledgeGapTaskLink type may change without a deprecation period.

Reading knowledgeGap also requires the knowledgeGap:read permission. A task you created yourself has an empty sourceLinks.

Query

query getTaskKnowledgeGap($taskId: ID!) {
  task(taskId: $taskId) {
    id
    ref
    status
    sourceLinks {
      edges {
        node {
          sourceType
          sourceId
          ... on KnowledgeGapTaskLink {
            knowledgeGap {
              id
              title
              description
              lastSeenAt {
                iso8601
              }
            }
          }
        }
      }
    }
  }
}

Variables

{
  "taskId": "ta_01HXXXXXXXXXXXXXXXXXXXXXXX"
}