How are Forge points-quota costs counted for changelog/bulkfetch and search/jql?

Hi all,

We’re building a Forge dashboard gadget that reads issue status history so it can show flow time and aging. It calls two Jira Cloud REST endpoints as the user (asUser / requestJira):

  • POST /rest/api/3/search/jql: pages of 100 issues with a short fields list
  • POST /rest/api/3/changelog/bulkfetch: up to 1,000 issues per request, filtered with fieldIds: ["status", "assignee", "project"]

We want to budget against the points-based app quota (65,000 points/hour for Tier 1, shared across tenants), and the rate-limiting docs list the per-object costs. What we couldn’t find is how those costs apply to these two endpoints:

  1. search/jql: is it 1 point per request plus 1 per issue returned? Does the number of fields requested change the cost?
  2. changelog/bulkfetch: what counts as an “object”?
    • each issue in issueIdsOrKeys,
    • each change history (changelog entry) returned, or
    • each history plus its author (a user object at 2 points)?
  3. Does filtering with fieldIds lower the cost because fewer histories come back, or is the cost set by the issues requested?
  4. Is a request that returns a nextPageToken (a partial page) charged differently from a full page?

What we see today on a development-environment app (api.asUser().requestJira calls from a resolver):

  • Every response carries only the burst policy: RateLimit-Policy: "jira-burst-based";q=100;w=1, plus X-RateLimit-Limit: 200.
  • There is no global-app-quota or tenant-app-quota entry in RateLimit-Policy, RateLimit, or the Beta- variants of those headers, even after a few hundred calls.

So we can’t measure the points cost ourselves. Should we expect the quota headers to show up on development installs at all, or only once an app is enrolled in the phased enforcement? Is there a way to see an app’s points usage before then?

For now we budget against a worst case of 1 per request + 1 per issue + 3 per change history, and we stop when RateLimit reports a remaining value or X-RateLimit-NearLimit: true appears. If that’s far too pessimistic, or misses something, we’d really appreciate a pointer.

Thanks!

Hi @CamdenHuffman,

The docs don’t give a cost for search/jql or changelog/bulkfetch. The rate limiting page adds points “for each object involved” on top of a base cost of 1, but it doesn’t define an object, so that worst case is neither confirmed nor refuted.

Your resolver calls count. Staff said the same calls made from the gadget’s frontend with requestJira from @forge/bridge are exempt (97828 #133, again in #168). That could change with notice. One partner measured search/jql at 1 + the results returned (#151).

Before enforcement, the docs and CHANGE-3080 say you should get a Beta-RateLimit-Policy with global-app-quota. No quota entry at all isn’t covered. We saw an unprefixed one on a dev install with asApp. I haven’t tried asUser, so the auth path could be the difference.

Read r only on the global-app-quota entry (tenant-app-quota on Tier 2). The jira-burst-based entry has its own per-second r, so a plain check for any remaining value fires on it. Before enforcement it’s Beta-RateLimit and X-Beta-RateLimit-NearLimit. The respects rate limits guide splits entries by policy name.

Staff planned a developer console points view in December (#84). I haven’t seen it ship.

For bulkfetch, open an ECOHELP request at https://developer.atlassian.com/support with your exact headers.