nav[aria-label="Primary Navigation"] { padding: 0; & ul { list-style: none; width: 100%; display: flex; flex-direction: row; justify-content: start; align-items: start; gap: 30px; padding: 0; & li { margin: 0; } & ul li { list-style: none; } } }

How to Check Used and Total License Counts in Atlassian Cloud

aslead-community

Regarding Atlassian Cloud, could you please advise whether there is a method to obtain the number of licenses currently in use and the total contracted license count?

■ Background and Purpose
We aim to regularly monitor license consumption and proactively detect when usage approaches the upper limit. We plan to automate this retrieval using the API.

■ Items to Confirm
Is there a REST API available to obtain the following:

Number of active users
Number of licenses in use (i.e., the count of billable users reflected in Atlassian's billing)
Total license count

By "number of licenses in use," we refer to the count of billable users (the number reflected in Atlassian's billing). If there are any considerations or points of caution regarding the counting method—such as differences in billable status due to inactive users, groups, roles, or other factors—please also advise us.

We have conducted our own investigation and verification, and the results are documented below.

Regarding the number of active users:
We believe it is feasible to count active users within a specified period using the productAccess.lastActiveTimestamp field within the following API endpoint:
https://developer.atlassian.com/cloud/admin/organization/rest/api-group-users/#api-v2-orgs-orgid-directories-directoryid-users-search-post
Is our understanding correct?

Regarding the total license count:
In the response of the following API endpoint:
https://developer.atlassian.com/cloud/admin/organization/rest/api-group-workspaces/#api-v2-orgs-orgid-workspaces-post
we observed a key named softCapacityLimit within relationships.entitlement.attributes, which appears to match the total license count. However, this key is not documented in the official documentation. Is it acceptable to treat this key as the total license count?

Best regards,

NRI

Accepted answers

All comments

Mihai_LeanZero

Not an exact billable count, as far as I know. AX-227 is still open for that.

Closest is users/count in the v2 org API. It takes resourceIds (the product), roleIds and status. Count atlassian/user plus atlassian/admin, status active, per product. The role list in the docs marks customer, contributor and basic as non-billable, so that should land near the billed number. Not run against a real org here. Reconcile with admin.atlassian.com/billing, Manage on the subscription, before alerting on it.

softCapacityLimit isn't documented. The workspaces docs describe attributes.capacity, which may be present for Jira and Confluence when licence data is available. usage is Bitbucket-only. Same check against Billing.

lastActiveTimestamp for active users is fine.

Two quirks for the threshold. Users count once product access is granted, logged in or not. Monthly plans bill the highest count in the period, so mid-cycle removals don't lower it.

Jira also has approximateLicenseCount. Cached up to 7 days.

Votes on AX-227 and AX-233 help, or CONFCLOUD-37100 for confluence

Gor Greyan

Hi @aslead-community,

Mihai has already covered the main API limitations quite well.

One additional recommendation for automated license monitoring is to distinguish between active users, provisioned users with product access, and billable users, since these numbers may differ.

For monitoring, you could use the Organizations REST API to periodically retrieve users with product access and estimate license consumption per product.

However, I wouldn't recommend relying on softCapacityLimit for production automation, since it's undocumented and could change without notice.

A practical approach would be to:

Calculate license consumption from users with product access.

Periodically reconcile the results with Atlassian Administration → Billing.

Configure alerts when estimated consumption approaches your licensed capacity.

Until Atlassian provides an official API exposing exact billable license consumption and subscription limits, this would be a reasonable workaround.

Hope this helps!

Regards,
Gor

aslead-community

Hello,

Thank you for your response.

I would like to confirm one point regarding the content of your reply.

Regarding the users/count endpoint you provided, requesting it returns an HTTP status code of 404.

Since users/search works correctly and returns values, I believe the Org ID, Directory ID, and token are correct.

Is this endpoint currently available?

I executed the verification using the following command, utilizing 1Password's op run feature:

op run -- sh -c 'curl --request GET --url "https://api.atlassian.com/admin/v2/orgs/{$ATLASSIAN_CLOUD_ORG_ID}/directories/{$ATLASSIAN_CLOUD_DIRECTORY_ID}/users/count" --header "Authorization: Bearer $ATLASSIAN_CLOUD_ADMIN_TOKEN" --header "Accept: application/json"'

The response received was as follows:

{"timestamp":"2026-10-21T04:44:03.932Z","path":"/api/admin/v2/orgs/<concealed by 1Password>/directories/<concealed by 1Password>/users/count","status":404,"error":"Not Found","requestId":"e89f5be2-362536","message":""}

Best regards,

NRI

Josh

Hi @aslead-community, the endpoint does exist. It is listed in the Organizations REST API docs as GET /v2/orgs/{orgId}/directories/{directoryId}/users/count: https://developer.atlassian.com/cloud/admin/organization/rest/api-group-users/

Looking at your command, I think the 404 comes from the shell, not the API. In sh, {$ATLASSIAN_CLOUD_ORG_ID} does not mean "the variable". The shell expands $ATLASSIAN_CLOUD_ORG_ID and leaves the curly braces in place, so the URL that goes out is /orgs/{your-org-id}/directories/{your-directory-id}/users/count with literal braces. That path doesn't match anything, so you get 404. 1Password masks the values in the error, which hides the braces.

Try it with the braces inside the dollar sign:

op run -- sh -c 'curl --request GET \
  --url "https://api.atlassian.com/admin/v2/orgs/${ATLASSIAN_CLOUD_ORG_ID}/directories/${ATLASSIAN_CLOUD_DIRECTORY_ID}/users/count" \
  --header "Authorization: Bearer $ATLASSIAN_CLOUD_ADMIN_TOKEN" \
  --header "Accept: application/json"'

If your users/search call works, compare how the URL is written there. I'd expect it to use ${...} or no braces at all.

If it still returns 404 after that, check two things. First, the directory ID is the same one that works for users/search. Second, the API key has the scopes the endpoint needs, since a key without access can return an error that looks like the path is wrong. The filters (resourceIds, roleIds, status) are query parameters on this GET.

Mihai_LeanZero

It's there and it works. Hadn't run it against a real org in the first answer, so ran it today on a test org, your exact command included. Count came back. Braces are fine too, curl drops them itself.

That 404 with an empty message is what the API returns when the org or directory id in the path doesn't resolve. Empty segment or a trailing newline in the variable does it too.

Search working with the same ids? Then compare how the two commands get them. Typed in on one, variable on the other, that's where I'd look.

Quickest check, "-" as the directory id (the docs say it widens the scope to all directories you manage):

op run -- sh -c 'curl -s "https://api.atlassian.com/admin/v2/orgs/${ATLASSIAN_CLOUD_ORG_ID}/directories/-/users/count?status=active" -H "Authorization: Bearer $ATLASSIAN_CLOUD_ADMIN_TOKEN" -H "Accept: application/json"'

Count back? Then it's probably the directory value.

resourceIds later want ARI format, the docs' example is ari:cloud:jira-core::site/1, with the site's cloud id in place of the 1.

aslead-community

Hello,

Thank you for your response.

For isolation purposes, I set the directory ID to -, but the output was as follows:

❯ op run -- sh -c 'curl --request GET --url "https://api.atlassian.com/admin/v2/orgs/$ATLASSIAN_CLOUD_ADMIN_ORG_ID/directories/-/users/count" --header "Authorization: Bearer $ATLASSIAN_CLOUD_ADMIN_USER_COUNT_TOKEN" --header "Accept: application/json"' | jq .


{

  "count": 0

}

For reference, I am also providing the output from other endpoints:

❯ op run -- sh -c 'curl --request GET --url "https://api.atlassian.com/admin/v2/orgs/$ATLASSIAN_CLOUD_ADMIN_ORG_ID/directories/-/users/stats" --header "Authorization: Bearer $ATLASSIAN_CLOUD_ADMIN_USER_COUNT_TOKEN" --header "Accept: application/json"' | jq .


{

  "roles": [

    {

      "roleId": "atlassian/org-admin",

      "count": 7

    }

  ],

  "accountStatus": [

    {

      "status": "active",

      "count": 658

    },

    {

      "status": "inactive",

      "count": 5102

    }

  ]

}

op run -- sh -c 'curl --request POST --url "https://api.atlassian.com/admin/v2/orgs/$ATLASSIAN_CLOUD_ADMIN_ORG_ID/directories/-/users/search" --header "Authorization: Bearer $ATLASSIAN_CLOUD_ADMIN_USER_COUNT_TOKEN" --header "Accept: application/json"' | jq . | head -n 10


{

  "data": [

    {

      "accountId": "5ec385bcde8fe30c44a0e6b2",

      "accountType": "atlassian",

      "status": "suspended",

      "accountStatus": "active",

      "membershipStatus": "suspended",

      "addedToOrg": "2026-05-22T06:26:08.821499Z",

      "deactivatedOn": null,

Regarding the organization ID, all commands retrieved it via 1Password.

Best regards,

NRI

Mihai_LeanZero

Hi @aslead-community,

I couldn't reproduce the 0. On a test org with 23 members, the bare count returned 23 with "-" and with the real directory id. Suspended members were included. The docs say all directories and managed accounts are counted by default:
https://developer.atlassian.com/cloud/admin/organization/rest/api-group-users/

I'd rule out the key's scopes next. Create an API key without scopes in Atlassian Administration and run the same count with it. If that returns a number, the scopes on your key are the likely cause.
https://support.atlassian.com/organization-administration/docs/manage-an-organization-with-the-admin-apis/

On the test org, the "inactive" in stats matched count?membershipStatus=suspended (11 and 11). count?accountStatus=inactive gave 0.

For used licences, count per product and site:
.../directories/-/users/count?status=active&roleIds=atlassian/user&roleIds=atlassian/admin&resourceIds=<product ARI>

For contracted seats, attributes.capacity on workspaces is still the closest I know of, when it's present. I'd check it against the billing page.

aslead-community

Hello,

Thank you for your response.

Regarding the retrieval of values from the users/count endpoint, as you advised, we were able to successfully obtain the values by making a request with a token that has no scope restrictions. Please note that the required scopes for this endpoint are not explicitly stated in the documentation.

Additionally, regarding the total number of licenses, the attributes.capacity value was not present in the response from the Workspaces API.

❯ op run -- sh -c 'curl --request POST  --url 'https://api.atlassian.com/admin/v2/orgs/18k8ba6d-b39d-1153-6648-671c720bbd9d/workspaces' --header "Authorization: Bearer $ATLASSIAN_CLOUD_ADMIN_NO_SCOPE_TOKEN"  --header "Accept: application/json" --header "Content-Type: application/json"' | jq . | grep -A 30  '"type": "Jira Software"'

  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current

                                 Dload  Upload   Total   Spent    Left  Speed

100 40792  100 40792    0     0  84034      0 --:--:-- --:--:-- --:--:-- 83934

      "type": "Jira Software",

      "links": {

        "self": "https://api.atlassian.com/admin/v1/workspaces/ari%3Acloud%3Ajira-software%3A%3Asite%2F11d2a524-7efc-4654-838a-798916b7e2e1"

      },

      "appType": "Atlassian",

      "attributes": {

        "name": "honda-tabby",

        "typeKey": "jira-software",

        "type": "Jira Software",

        "icons": {},

        "avatars": {},

        "owner": "ari:cloud:platform::org/<concealed by 1Password>",

        "labels": [],

        "status": "online",

        "statusDetails": [],

        "createdAt": "2026-02-16T09:04:46.066Z",

        "hostUrl": "https://honda-tabby.atlassian.net",

        "directory": "<concealed by 1Password>",

        "unit": "ari:cloud:platform::collaboration-context/20453def-d977-4072-8005-f4d37ae30faf",

        "realm": "jp",

        "regions": [

          "ap-northeast-1"

        ]

      },

      "relationships": {

        "entitlement": [

          {

            "id": "72d0351d-f78d-36fb-9908-d6a7fe56cba7",

            "links": {

              "self": "https://api.atlassian.com/admin/v1/workspaces/ari%3Acloud%3Ajira-software%3A%3Asite%2F11d2a524-7efc-4654-838a-798916b7e2e1/entitlements/72d0351d-f78d-36fb-9908-d6a7fe56cba7"

            },

            "type": "entitlements",

            "attributes": {

              "ccpEntitlementId": "72d0351d-f78d-36fb-9908-d6a7fe56cba7",

              "planKey": "Enterprise",

              "billingSourceSystem": "CCP",

              "productId": "d8a847a4-cde4-4c50-8ea1-dc3d4193214f",

              "plan": "Enterprise",

              "key": "jira-software.ondemand",

  "type": "Jira Software",

  "links": {

    "self": "<https://api.atlassian.com/admin/v1/workspaces/ari%3Acloud%3Ajira-software%3A%3Asite%2Fed56ee03-ac6d-40e6-8139-ccbb595a56bc>"

  },

  "appType": "Atlassian",

  "attributes": {

    "name": "honda-tabby-sandbox",

    "typeKey": "jira-software",

    "type": "Jira Software",

    "icons": {},

    "avatars": {},

    "owner": "ari:cloud:platform::org/<concealed by 1Password>",

    "labels": [

      "sandbox"

    ],

    "status": "online",

    "statusDetails": [],

    "sandbox": {

      "type": "CHILD",

      "parentId": "11d2a524-7efc-4654-838a-798916b7e2e1"

    },

    "createdAt": "2026-03-23T00:47:51.585Z",

    "hostUrl": "<https://honda-tabby-sandbox.atlassian.net>",

    "directory": "<concealed by 1Password>",

    "unit": "ari:cloud:platform::collaboration-context/20453def-d977-4072-8005-f4d37ae30faf",

    "realm": "jp",

    "regions": [

      "ap-northeast-1"

    ]

  },

  "relationships": {

    "entitlement": [

      {

        "id": "7b588496-c9b0-3054-b90d-2aefafe6dd07",

        "links": {

          "self": "<https://api.atlassian.com/admin/v1/workspaces/ari%3Acloud%3Ajira-software%3A%3Asite%2Fed56ee03-ac6d-40e6-8139-ccbb595a56bc/entitlements/7b588496-c9b0-3054-b90d-2aefafe6dd07>"

        },

        "type": "entitlements",

        "attributes": {

For production use, we intend to operate using tokens granted only the necessary scopes from a security perspective.

Could you please advise on the specific scopes required to obtain the number of used licenses, the total number of licenses, and the number of active users, respectively?

Best regards,

NRI

Mihai_LeanZero

Hi @aslead-community,

Your users/count result matches the docs. That endpoint isn't on the scopes page, and the page says unlisted endpoints need a key without scopes. The scoped key returning 0 rather than an error is odd, so a 0 from it can't be trusted.
https://developer.atlassian.com/cloud/admin/scopes/

Workspaces needs read:workspaces:admin. The spec only says capacity may be present for Jira and Confluence sites when licence data is available, and softCapacityLimit isn't in the spec. No scope fixes that, so contracted seats are best taken from the billing page or Atlassian support.

For active users, users/stats needs read:directories:admin, but its "active" means account status. lastActiveTimestamp is also in the GET .../directories/-/users response, and that one is listed under read:directories:admin, so you don't need search for it.

That leaves only count on the no-scope key. A key without scopes can do everything the Admin APIs can, writes included, so I'd keep it in the one job that runs the count.
https://support.atlassian.com/organization-administration/docs/manage-an-organization-with-the-admin-apis/

I haven't tested whether read:directories:admin covers count.

aslead-community

Hello,

Thank you for your response.
I understand the required tokens for each endpoint.

I'd like to shift topics slightly and seek your advice.

We have confirmed that the value returned by the users/count endpoint matches the billable user count displayed in the UI.
While users/count accepts parameters such as resourceIds, roleIds, and status, we tested the following alternative approach using the search endpoint:
https://developer.atlassian.com/cloud/admin/organization/rest/api-group-users/#api-v2-orgs-orgid-directories-directoryid-users-search-post

For each resourceId, we aggregated the user count by filtering for roleIds of atlassian/user and atlassian/admin, and status of Active. The resulting total matched the value from users/count.

Given this alignment, would it be acceptable to substitute the users/count endpoint with this search-based aggregation method?
Since the search endpoint successfully returns data using a scoped token, we would prefer to adopt this approach if feasible.

Best regards,

NRI

Mihai_LeanZero

Hi @aslead-community,

Per product it can replace count, but an org total needs a dedupe first.

search takes the same filters as count and returns an accountId on each row. If you run it once per resourceId, a person with two products comes back in both result sets and a plain sum counts them twice. For the org number, count distinct accountId.

Billing is per app too, unless it's a collection, which counts each user once across its apps.
https://support.atlassian.com/subscriptions-and-billing/docs/manage-users-and-user-tiers/

The scoped key is the weak spot. The scopes page lists neither search nor count, so that access isn't documented and could change.

My last reply was wrong to point at GET .../users. That endpoint is deprecated and stops working after June 30, 2027, with search named as its replacement.
https://developer.atlassian.com/cloud/admin/organization/rest/api-group-users/

Page at limit 100 and follow links.next. I haven't tested this myself.

Welcome!

It looks like you're new here. Sign in or register to get started.

Quick Links

Find more posts tagged with

jira-cloud

confluence-cloud