Search query tips for the Goals & Projects GraphQL API

[#1]

Hi Community!

We've just published search query reference documentation for the Goals and Projects GraphQL API. If you've been building on top of goals_search or projects_search, or wanted to give it a go, this is the guide you've been waiting for.

A preview of the Goals GraphQL API search query reference documentation.

The Goals and Projects GraphQL API gives you programmatic access to your organisation's goals and projects data. That opens up use cases that are difficult to achieve through the UI alone - building custom reporting dashboards, feeding status data into a BI tool, automating progress summaries, or getting an aggregated view of what's on track across an entire org hierarchy. The search query language is what makes those queries precise and efficient, letting you filter exactly what you need server-side rather than pulling everything and processing it in your application.

What's in the docs

The documentation covers everything you need to write effective search queries:

• Query syntax - how clauses work, how to combine them with AND / OR, and how to use parentheses to control precedence

• Operators - the full set including =, !=, LIKE, IS EMPTY, IS IN, and date comparisons like >= and <=

• Available fields - a complete field reference for both goals and projects, including fields like status, owner, label, targetDate, reporting_line, and more

• Sorting - how to sort results by name, creation date, target date, latest update, and other fields

• Pagination - cursor-based pagination using the standard Relay connection pattern

• Query cost limits - each field clause carries a cost, and queries have a complexity budget (30 for goals, 35 for projects). The docs explain which fields are expensive and how to stay within budget

A quick example

To give you a sense of what's possible, here's a query that returns all on-track goals within a manager's reporting chain, sorted by target date:

query {
  goals_search(
    containerId: "ari:cloud:townsquare::site/{siteId}"
    searchString: "reporting_line = \"{managerAccountId}\" AND status = on_track"
    first: 50
    sort: [TARGET_DATE_ASC]
  ) {
    edges {
      node { name targetDate owner { name } }
    }
    pageInfo { hasNextPage endCursor }
  }
}

The reporting_line field traverses the full org hierarchy - so this returns goals owned by the manager and all of their direct and indirect reports in a single query.

Read the docs

The full reference is available for both APIs:

• Goals search query documentation

• Projects search query documentation

If you have questions or feedback on the docs, drop them in the comments below. We'd love to learn more about how you're using the API!

[Josh]

Thanks for sharing these tips, @Charlie Marriott !

The ability to traverse the full org hierarchy is excellent. Would love to see that in other areas of the platform, especially Jira / JSM / JPD.