RunDiffusion Logo
Skip to content

List teams

Every team in a company, for administrative reads.

On this page

Every team in a company. This is an administrative view for tooling that manages an organization, not an account picker: the accounts you can act under are on Get identity, which already returns them.

Reading it requires the MANAGE_TEAMS permission on the company, because listing a company's teams exposes its structure and Get a team then exposes every member's email address.

That permission comes from the caller's company role, which is a separate grant from their team role. Get identity returns it under company_permissions, not in the permissions map beside it. See Two roles, two maps.

GEThttps://api2.rundiffusion.com/api/v2/teams
AcceptsOAuth device flowCompany API Access Token

Request

Headers

AuthorizationstringRequired
Bearer token. This endpoint accepts an OAuth device flow token or a Company API Access Token. A Personal API Access Token is refused, because it reaches only its owner's own resources and is not scoped to a company. See Authentication.Authorization: Bearer eyJhbGciOi…

Query

cursorstringoptional
Opaque pagination token. When a response has has_more true, pass its next_cursor here to get the following page. Do not construct or parse one.https://api2.rundiffusion.com/api/v2/teams?cursor=2D8NEx…
limitintegeroptionaldefault 24
Page size, from 1 to 100.https://api2.rundiffusion.com/api/v2/teams?limit=10
company_idstringoptional
The company to read. Required with OAuth, which names a person rather than a company. A Company API Access Token already names its company, so it does not need this. Get identity returns it on every TEAM account.https://api2.rundiffusion.com/api/v2/teams?company_id=Cm4pQ7…
is_activebooleanoptional
Filter by activation state. true returns activated teams, false returns deactivated ones. Omit it to get both, which is the default.https://api2.rundiffusion.com/api/v2/teams?is_active=true

Naming the company

A Company API Access Token already names the company it acts on, so it needs no parameter:

bash
curl "https://api2.rundiffusion.com/api/v2/teams" \
  -H "Authorization: Bearer $RUNDIFFUSION_COMPANY_TOKEN"

OAuth is a user credential with no company of its own, and a user can belong to teams in more than one company, so there is nothing to infer. Name the company with company_id, which Get identity returns on every TEAM account:

bash
curl "https://api2.rundiffusion.com/api/v2/teams?company_id=Cm4pQ7…" \
  -H "Authorization: Bearer $RUNDIFFUSION_TOKEN"

Note that company_id is not the account selection team_id performs everywhere else: this endpoint answers for a company, never for one team inside it.

A Personal API Access Token is refused.

Response

200 OK with one page of the company's teams, newest first.

json
{
  "data": [
    {
      "id": "2D8NEx…",
      "created": "2026-03-14T09:02:11+00:00",
      "name": "Design Studio",
      "is_active": true
    }
  ],
  "has_more": false,
  "next_cursor": null
}
dataarray
The teams on this page, newest first. Empty when the company has none, which is not an error.
has_moreboolean
Whether more pages exist beyond this one. This is the flag to branch on when paging.
next_cursorstring | null
Pass this back as cursor to fetch the next page. Null on the last page.

Team object

idstring
The team ID. This is the value you send as team_id on the endpoints that take an account selection.
createdstring (ISO 8601) | null
When the team was created, in UTC.
namestring | null
The team's display name.
is_activeboolean
Whether the team is activated. A deactivated team still appears here unless you filter it out.

Paging

Cursor paginated, the same way as every other listing. Read has_more, and when it is true send next_cursor back as cursor.

The cursor is tied to the filter it was issued under. Changing is_active partway through a walk invalidates it and returns 400 INVALID_CURSOR rather than quietly resuming somewhere else in a different result set, so keep the filter constant for the length of a walk.

Errors

Status codes

403PERMISSION_DENIED
The caller lacks MANAGE_TEAMS on the company, or presented a Personal API Access Token, or presented a user credential without naming a company. The message says which.
404TEAM_NOT_FOUND
The company named does not exist, or has no teams the caller may read.
400INVALID_CURSOR
The cursor no longer matches this listing, which happens if you change is_active partway through a walk. Restart the walk without a cursor.
401UNAUTHENTICATED
Missing, malformed, or expired token. Refresh it and retry.
429RATE_LIMITED
Too many requests. See Rate limits.

View as Markdown