Search Queries for Projects

Overview

The projects_search query supports a powerful search query language for filtering projects. 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 projects_search.

Quick start

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

1
2
query {
  projects_search(
    containerId: "ari:cloud:townsquare::site/{siteId}"
    searchString: "name LIKE launch"
    first: 10
  ) {
    edges {
      node {
        name
        state {
          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 { projects_search(containerId: \"ari:cloud:townsquare::site/{siteId}\", searchString: \"name LIKE launch\", first: 10) { edges { node { name state { 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 Project" — exact match on name
• name LIKE roadmap — partial/fuzzy match on name
• status = on_track — filter by status
• archived = false — exclude archived projects
• 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):

Project fields

The following fields are available when searching projects with projects_search:

Sorting

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

CREATION_DATE_ASC, CREATION_DATE_DESC, NAME_ASC, NAME_DESC, STATUS_ASC, STATUS_DESC, START_DATE_ASC, START_DATE_DESC, TARGET_DATE_ASC, TARGET_DATE_DESC, LATEST_UPDATE_DATE_ASC, LATEST_UPDATE_DATE_DESC, WATCHING_ASC, WATCHING_DESC

Pagination

projects_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 {
  projects_search(
    containerId: "ari:cloud:townsquare::site/{siteId}"
    searchString: "status = on_track"
    first: 25
    after: "eyJpZCI6MTAwfQ=="
  ) {
    edges {
      node {
        name
      }
    }
    pageInfo {
      endCursor
      hasNextPage
    }
  }
}

Examples

Search for projects with a specific label

1
2
query {
  projects_search(
    containerId: "ari:cloud:townsquare::site/{siteId}"
    searchString: "label = \"engineering\" AND archived = false"
    first: 20
    sort: [LATEST_UPDATE_DATE_DESC]
  ) {
    edges {
      node {
        name
        state {
          value
        }
        tags {
          edges {
            node {
              name
            }
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Complex query with grouping

1
2
query {
  projects_search(
    containerId: "ari:cloud:townsquare::site/{siteId}"
    searchString: "(status = off_track OR status = at_risk) AND type = PROJECT AND archived = false"
    first: 10
  ) {
    edges {
      node {
        name
        state {
          value
        }
      }
    }
  }
}

Full-text search across projects

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

1
2
query {
  projects_search(
    containerId: "ari:cloud:townsquare::site/{siteId}"
    searchString: "search LIKE \"migration\" AND status = on_track AND type = PROJECT"
    first: 20
    sort: [LATEST_UPDATE_DATE_DESC]
  ) {
    edges {
      node {
        name
        state {
          value
        }
      }
    }
  }
}

Find all projects under a manager's reporting line

The reporting_line field finds projects 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 {
  projects_search(
    containerId: "ari:cloud:townsquare::site/{siteId}"
    searchString: "reporting_line = \"{managerAccountId}\" AND (status = off_track OR status = at_risk)"
    first: 20
  ) {
    edges {
      node {
        name
        owner {
          aaid
        }
        state {
          value
        }
      }
    }
  }
}

This is useful for getting a birds-eye view of at-risk projects across an entire org.

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.

Projects budget: 35

Field costs

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

For example, a query like search LIKE "migration" AND reporting_line = "{id}" AND label = "platform" has a total cost of 5 + 5 + 5 = 15, which is within budget. But combining seven cost-5 fields would hit 35 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.