Search Queries for Goals

Overview

The goals_search query supports a powerful search query language for filtering goals. This guide explains the query syntax, available fields, operators, sorting, pagination, and query cost limits.

The query syntax is inspired by JQL (Jira Query Language) and is designed to be human-readable and flexible. You pass search queries as the searchString parameter to goals_search.

Quick start

Here's a simple example that searches for all goals with "Q3" in their name:

1
2
query {
  goals_search(
    containerId: "ari:cloud:townsquare::site/{siteId}"
    searchString: "name LIKE Q3"
    first: 10
  ) {
    edges {
      node {
        name
        status {
          value
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

And here's a cURL command for the same query:

1
2
curl -X POST 'https://{subdomain}.atlassian.net/gateway/api/graphql' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic <YOUR_BASE_64_TOKEN_HERE>' \
  --data '{"query":"query { goals_search(containerId: \"ari:cloud:townsquare::site/{siteId}\", searchString: \"name LIKE Q3\", first: 10) { edges { node { name status { value } } } pageInfo { hasNextPage endCursor } } }"}'

Query syntax

Clauses

A search query is made up of one or more clauses. Each clause has the form:

1
2
field operator value

For example:

• name = "My Goal" — exact match on name
• name LIKE roadmap — partial/fuzzy match on name
• status = on_track — filter by status
• archived = false — exclude archived goals
• owner = "60eeec6bf749c4006801261b" — filter by owner's Atlassian account ID

If a value contains spaces, wrap it in double quotes: name LIKE "product launch".

Combining clauses

You can combine multiple clauses with AND and OR:

• status = on_track AND owner = "60eeec6bf749c4006801261b" — both conditions must match
• status = off_track OR status = at_risk — either condition can match

Operator precedence: AND binds more tightly than OR. Use parentheses to control grouping:

1
2
(status = off_track OR status = at_risk) AND label = "engineering"

Grouping with parentheses

Parentheses can be nested to create complex queries:

1
2
(name LIKE launch AND status = on_track) OR (label = "priority" AND owner = "60eeec6bf749c4006801261b")

Operators

The following operators are available (not all operators are supported by every field — see the field reference table below):

Goal fields

The following fields are available when searching goals with goals_search:

Sorting

You can sort results by passing a sort parameter to goals_search. The available sort options are:

CREATION_DATE_ASC, CREATION_DATE_DESC, NAME_ASC, NAME_DESC, SCORE_ASC, SCORE_DESC, TARGET_DATE_ASC, TARGET_DATE_DESC, LATEST_UPDATE_DATE_ASC, LATEST_UPDATE_DATE_DESC, WATCHING_ASC, WATCHING_DESC

Pagination

goals_search supports cursor-based pagination using the standard Relay connection pattern:

• first — the maximum number of results to return per page
• after — a cursor string from a previous response, indicating where to continue

Every response includes a pageInfo block:

1
2
pageInfo {
  startCursor
  endCursor
  hasNextPage
  hasPreviousPage
}

To fetch the next page, pass the endCursor value from the previous response as the after parameter in your next request.

Pagination example

1
2
query {
  goals_search(
    containerId: "ari:cloud:townsquare::site/{siteId}"
    searchString: "status = on_track"
    first: 25
    after: "eyJpZCI6MTAwfQ=="
  ) {
    edges {
      node {
        name
      }
    }
    pageInfo {
      endCursor
      hasNextPage
    }
  }
}

Examples

Search for on-track goals owned by a specific user

1
2
query {
  goals_search(
    containerId: "ari:cloud:townsquare::site/{siteId}"
    searchString: "status = on_track AND owner = \"{accountId}\""
    first: 10
    sort: [NAME_ASC]
  ) {
    edges {
      node {
        name
        status {
          value
        }
        owner {
          aaid
        }
        targetDate
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Search for goals with a target date in Q1 2026

1
2
query {
  goals_search(
    containerId: "ari:cloud:townsquare::site/{siteId}"
    searchString: "targetDate >= 2026-01-01 AND targetDate <= 2026-03-31"
    first: 50
    sort: [TARGET_DATE_ASC]
  ) {
    edges {
      node {
        name
        targetDate
        phase {
          name
        }
      }
    }
  }
}

Full-text search across goals

The search field searches across goal name, tags, and key. Use the LIKE operator:

1
2
query {
  goals_search(
    containerId: "ari:cloud:townsquare::site/{siteId}"
    searchString: "search LIKE \"quarterly revenue\""
    first: 10
  ) {
    edges {
      node {
        name
        owner {
          aaid
        }
      }
    }
  }
}

Find all goals under a manager's reporting line

The reporting_line field finds goals owned by a specific user or anyone in their reporting chain (direct and indirect reports). Pass the manager's Atlassian account ID:

1
2
query {
  goals_search(
    containerId: "ari:cloud:townsquare::site/{siteId}"
    searchString: "reporting_line = \"{managerAccountId}\" AND phase = in_progress"
    first: 50
    sort: [TARGET_DATE_ASC]
  ) {
    edges {
      node {
        name
        owner {
          aaid
        }
        status {
          value
        }
        targetDate
      }
    }
  }
}

Combining search with reporting line

1
2
query {
  goals_search(
    containerId: "ari:cloud:townsquare::site/{siteId}"
    searchString: "reporting_line = \"{managerAccountId}\" AND search LIKE \"revenue\" AND status_phase = on_track"
    first: 10
  ) {
    edges {
      node {
        name
        owner {
          aaid
        }
        score
      }
    }
  }
}

Query limits

To protect system performance, each search query has a complexity budget. Every field clause in your query adds a cost, and if the total cost meets or exceeds the budget, the query will be rejected with an error.

Goals budget: 30

Field costs

Each clause in your query adds the following cost based on the field used:

For example, a query like search LIKE "revenue" AND reporting_line = "{id}" AND label = "finance" has a total cost of 5 + 5 + 5 = 15, which is within budget. But combining six cost-5 fields would hit 30 and be rejected.

If your query is rejected for being over budget, simplify it by reducing the number of expensive clauses or splitting the query into multiple requests.

Tips

• Start simple: Begin with a single clause and add more as needed.
• Use parentheses: When mixing AND and OR, use parentheses to make your intent clear.
• Quote values with spaces: Wrap multi-word values in double quotes (e.g., name LIKE "product launch").
• Operators are case-insensitive: LIKE, like, and Like all work.
• Field names are case-insensitive: Name, name, and NAME all work.
• Use search for broad queries: The search field searches across name and tags. Use it with LIKE.
• Pass an empty string for all results: If you want all results (unfiltered), pass an empty string "" as the searchString.