Monitor parallel test and queue usage with an API

Learn how to use the BrowserStack App Automate REST API to get real-time visibility into parallel test usage and queue size at the user and team level.

For team leads and administrators, BrowserStack provides a REST API to get a real-time snapshot of your organization’s parallel session consumption. This helps you manage resources, understand queue pressure, and ensure fair usage across teams.

Key objectives

• Understand real-time parallel usage at user and team levels.

• Monitor queue pressure and size when parallel limits are reached.

• Identify the user and team associated with a specific build.

• Enable data-driven decisions to stop or de-prioritize ongoing tests.

Fetch real-time usage data

Send an authenticated GET request to the following endpoint to retrieve current usage data.

Parallel allocation logic

The number of parallels a user can see and utilize depends on your organization’s configuration.

Example Scenario: An organization has purchased 100 parallels.

• Team A is assigned 20 dedicated parallels.
• The remaining 80 parallels are shared among all other users and teams (e.g., Team B, and users not assigned to a specific team).

In this case:

• Users in Team A (e.g., User 3, User 4) sees a maximum of 20 parallels on their dashboard and can only use up to that dedicated limit.
• All other users (e.g., User 1, User 2, User 5, User 6) see and share the remaining pool of 80 parallels.
• Admins are able to see all data, irrespective of the parallels assigned to them or their team.

Understand the API response

The API response varies slightly depending on whether your organization has configured teams.

Common meta object All responses contain a meta object with a summary of usage relevant to the user making the request.

"meta": {
  "generatedAt": "2025-06-27T07:21:05Z",
  "persona": "admin",
  "summary": {
    "totalParallelsUsed": 150,
    "maximumParallelsAllowed": 250,
    "totalQueuedSessions": 50,
    "maximumQueueAllowed": 100
  }
}`

• totalParallelsUsed: Current parallels in use by the user’s group (org or team).

• maximumParallelsAllowed: Maximum parallels available to the user’s group.

• totalQueuedSessions: Current number of queued sessions for the user’s group.

• maximumQueueAllowed: Maximum allowed queue length for the user’s group.

Example response (standard organization)

If your organization shares a single pool of parallels among all users, the response includes a usageByUserId array.

{
  "meta": {
    "generatedAt": "2025-07-16T07:49:05Z",
    "persona": "admin",
    "summary": {
      "totalParallelsUsed": 150,
      "maximumParallelsAllowed": 250,
      "totalQueuedSessions": 50,
      "maximumQueueAllowed": 100
    }
  },
  "usageByUserId": [
    {
      "userId": "12345",
      "userName": "Alice Dean",
      "parallelsUsed": 25,
      "sessionQueued": 25
    },
    {
      "userId": "56789",
      "userName": "Bob Rogers",
      "parallelsUsed": 10,
      "sessionQueued": 10
    },
    {
      "userId": "67890",
      "userName": "Charlie Smith",
      "parallelsUsed": 5,
      "sessionQueued": 0
    }
  ]
}

Example response (organizations with dedicated team parallels)

If your organization has assigned specific parallels to different teams, the response is structured with a usageByTeam array.

{
  "meta": { "...": "..." },
  "usageByTeam": [
    {
      "teamId": "Team A",
      "members": [
        {
          "userId": "12345",
          "userName": "Alice Dean",
          "parallelsUsed": 25,
          "sessionQueued": 25
        }
      ]
    },
    {
      "teamId": null,
      "members": [
        {
          "userId": "67890",
          "userName": "Charlie Smith",
          "parallelsUsed": 5,
          "sessionQueued": 0
        }
      ]
    }
  ]
}

Understanding maximumParallelsAllowed in team setups

The maximumParallelsAllowed value is context-specific. It reflects the number of parallels available to the user making the API call, not the total number purchased for the organization.

Scenario: An organization purchases 100 total parallels.

• Team A is assigned 20 dedicated parallels.

• All other users and teams share the remaining 80 parallels.

In this scenario:

• A user from Team A calling the API will see "maximumParallelsAllowed": 20. They can only use parallels from their team’s dedicated pool.

• A user from any other team (or no team) calling the API will see "maximumParallelsAllowed": 80. They draw from the shared pool of parallels.

This structure ensures that no single user sees the total purchased parallels (100), but rather the specific pool available to them.

Next steps

Now that you understand how to run and monitor parallel tests, you can View your results on the App Automate dashboard to see your parallel builds and analyze the results, logs, and video recordings for each device.