Multi-tenancy and teams

Many apps built on Stream have customers of their own. If you're building something like Slack, or a SaaS application like InVision, you want to make sure that one customer can't read another customer's data. Stream can be configured in multi-tenant mode so that users are organized in separated teams that cannot interact with each other.

Teams

Stream has the concept of teams for users and the resources they create, such as channels and calls. The purpose of teams is to provide a simple way to separate different groups of users within a single application.

If a user belongs to a team, the API will ensure that such user will only be able to connect to resources from the same team. Features such as user search are limited so that a user can only search for users from the same team by default.

When enabling multi-tenant mode all user requests will always ensure that the request applies to a team the user belongs to. For instance, if a user from team "blue" tries to delete a message that was created on a channel from team "red" the API will return an error. If a user doesn't have a team set, it will only have access to users and resources that don't have a team.

Enable Teams for your application

In order to use Teams, your application must have multi-tenant mode enabled. You can enable multi-tenant from the dashboard (Overview screen) or by calling the Application Settings endpoint.

// shows the current status
const appSettings = await client.getApp();
console.log(appSettings.app.multi_tenant_enabled);

// enables teams
client.updateApp({
  multi_tenant_enabled: true,
});

from getstream import Stream

client = Stream(api_key="{{ api_key }}", api_secret="{{ api_secret }}")
client.update_app(multi_tenant_enabled=True)

require 'getstream_ruby'
Models = GetStream::Generated::Models

client.common.update_app(Models::UpdateAppRequest.new(multi_tenant_enabled: true))

$client->updateApp(new Models\UpdateAppRequest(multiTenantEnabled: true));

res, _ := client.GetApp(ctx, &getstream.GetAppRequest{})
fmt.Println(res.Data.App.MultiTenantEnabled)

// enables teams
client.UpdateApp(ctx, &getstream.UpdateAppRequest{
  MultiTenantEnabled: getstream.PtrTo(true),
})

await client.UpdateAppAsync(new UpdateAppRequest { MultiTenantEnabled = true });

client.updateApp(UpdateAppRequest.builder()
    .multiTenantEnabled(true)
    .build()).execute();

User teams

When using teams, users must be created from your back-end and specify which teams they are a member of. This is necessary to ensure that a user cannot pick its own team.

client.upsertUsers([
  {
    id: "<user id>",
    name: "Sara",
    teams: ["red", "blue"],
  },
]);

from getstream.models import UpdateUserPartialRequest

client.update_users_partial(users=[
    UpdateUserPartialRequest(id=user_id, set={"teams": ["red", "blue"]})
])

require 'getstream_ruby'
Models = GetStream::Generated::Models

client.common.update_users_partial(Models::UpdateUsersPartialRequest.new(
  users: [Models::UpdateUserPartialRequest.new(
    id: user_id,
    set: { 'teams' => ['red', 'blue'] }
  )]
))

$client->updateUsersPartial(new Models\UpdateUsersPartialRequest(
    users: [new Models\UpdateUserPartialRequest(
        id: $userId,
        set: (object)["teams" => ["red", "blue"]],
    )],
));

resp, err := client.UpdateUsersPartial(ctx, &getstream.UpdateUsersPartialRequest{
  Users: []getstream.UpdateUserPartialRequest{
    {
      ID: user.ID,
      Set: map[string]any{
        "teams": []string{"red", "blue"},
      },
    },
  },
})

await client.UpdateUsersPartialAsync(new UpdateUsersPartialRequest
{
    Users = new List<UpdateUserPartialRequest>
    {
        new UpdateUserPartialRequest
        {
            ID = user.ID,
            Set = new Dictionary<string, object> { { "teams", new[] { "red", "blue" } } },
        },
    },
});

// Partial updating a user to be part of red and blue team
client.updateUsersPartial(UpdateUsersPartialRequest.builder()
    .users(List.of(UpdateUserPartialRequest.builder()
        .id(user.getId())
        .set(Map.of("teams", List.of("red", "blue")))
        .build()))
    .build()).execute();

Team resources

Channels and calls can be associated with a team. Users can create them client-side, but if their user is part of a team, they will have to specify a team or the request will be rejected with an error.

Setting a team on a channel or call ensures proper permission checking for a multi-tenant application. Keep in mind that you will still need to enforce that channel and call IDs are unique. Two common approaches: generate random UUIDs, or include the team name as a prefix to avoid collisions (ie. "red-general" and "blue-general" instead of just "general").

Creating chat channels with a team

// Creates the channel red-general for team red
client.channel("messaging", "red-general", { team: "red" }).create();

// Creates the red-general channel for the red team
client.createChannel(
  channelType = "messaging",
  channelId = "red-general",
  memberIds = listOf("user1", "user2"),
  extraData = mapOf("team" to "red")
).enqueue { result ->
  if (result is Result.Success) {
    val channel = result.value
  } else {
    // Handle Result.Failure
  }
}

// Creates the red-general channel for the red team
Map<String, Object> extraData = new HashMap<>();
List<String> memberIds = new LinkedList<>();
extraData.put("team", "red");
client.createChannel("messaging", "red-general", memberIds, extraData).enqueue(result -> {
  if (result.isSuccess()) {
    Channel channel = result.getOrNull();
  } else {
    // Handle error
  }
});

import StreamChat

/// 1: Create a `ChannelId` that represents the channel you want to create.
let channelId = ChannelId(type: .messaging, id: "general")

/// 2: Use the `ChatClient` to create a `ChatChannelController` with the `ChannelId`.
let channelController = try chatClient.channelController(
  createChannelWithId: channelId,
  name: "Channel Name",
  imageURL: nil,
  team: "red"
)

/// 3: Call `ChatChannelController.synchronize` to create the channel.
channelController.synchronize { error in
  if let error = error {
    /// 4: Handle possible errors
    print(error)
  }
}

// Creates the channel red-general for team red
final channel = client.channel(
  'messaging',
  id: 'red-general',
  extraData: {'team': 'red'},
);
await channel.create();

const FChannelProperties Properties{
  TEXT("messaging"),   // Type
  TEXT("red-general"),  // Id
  TEXT("red"),      // Team

};
Client->CreateChannel(
  Properties,
  [](UChatChannel* Channel)
  {
    // Channel created
  });

from getstream.models import ChannelInput

channel = client.chat.channel("messaging", "red-general")
channel.get_or_create(data=ChannelInput(created_by_id=user_id, team="red"))

require 'getstream_ruby'
Models = GetStream::Generated::Models

client.chat.get_or_create_channel('messaging', 'red-general', Models::ChannelGetOrCreateRequest.new(
  data: Models::ChannelInput.new(
    team: 'red',
    created_by_id: user_id
  )
))

$client->getOrCreateChannel("messaging", "red-general", new Models\ChannelGetOrCreateRequest(
    data: new Models\ChannelInput(
        team: "red",
        createdByID: $userId,
    ),
));

channel := client.Chat().Channel("messaging", "red-general")
resp, err := channel.GetOrCreate(ctx, &getstream.GetOrCreateChannelRequest{
  Data: &getstream.ChannelInput{
    CreatedByID: getstream.PtrTo(owner.ID),
    Team:        getstream.PtrTo("red"),
  },
})

await chat.GetOrCreateChannelAsync("messaging", "red-general", new ChannelGetOrCreateRequest
{
    Data = new ChannelInput
    {
        Team = "red",
        CreatedByID = user.ID,
    },
});

Creating video calls with a team

client.video.call("default", "red-team-weekly").create({
  data: { team: "red", created_by_id: "<user_id>" },
});

call = client.video.call("default", call_id)

response = call.create(
    data=CallRequest(
        created_by_id=user_id,
        team="blue",
    )
)

call = client.Video().Call("default", "callID")
response, err := call.GetOrCreate(ctx, &getstream.GetOrCreateCallRequest{
  Data: &getstream.CallRequest{
    Team:        getstream.PtrTo("blue"),
    CreatedByID: getstream.PtrTo("<user_id>"),
  },
})

var call = new Call("default", "callID", client.video());
call.getOrCreate(
  GetOrCreateCallRequest.builder()
    .data(CallRequest.builder()
      .team("blue")
      .createdByID("<user_id>")
      .build()
    )
    .build()
);

curl -X POST "https://video.stream-io-api.com/api/v2/video/call/${CALL_TYPE}/${CALL_ID}?api_key=${API_KEY}" \
  -H "Authorization: ${TOKEN}" \
  -H "stream-auth-type: jwt" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "created_by_id": "sacha@getstream.io",
      "team": "blue"
    }
  }'

User search

By default the user search will only return results from teams that the user is a part of. The API injects filter {teams: {$in: ["red", "blue"]}} for every request that doesn't already contain a filter for the teams field. If you want to query users from all teams, you have to provide an empty filter like this: {teams:{}}.

For server-side requests, this filter does not apply and you can search as usual and also filter by teams.

// search for users by name and team
client.queryUsers({
  payload: {
    filter_conditions: {
      name: "Nick",
      teams: { $in: ["red", "blue"] },
    },
  },
});

// search for users that are not part of any team
client.queryUsers({
  payload: {
    filter_conditions: {
      name: "Tom",
      teams: null,
    },
  },
});

# search for users by name and team
response = client.query_users(
    QueryUsersPayload(
        filter_conditions={
            "name": {"$eq": "Nick"},
            "teams": {"$in": ["red", "blue"]},
        }
    )
)

# search for users that are not part of any team
response = client.query_users(
    QueryUsersPayload(
        filter_conditions={
            "teams": None,
        }
    )
)

require 'getstream_ruby'
Models = GetStream::Generated::Models

# Server side usage, it searches all teams implicitly
client.common.query_users(
  Models::QueryUsersPayload.new(
    filter_conditions: { 'name' => { '$eq' => 'Nick' } }
  )
)

// Server side usage, it searches all teams implicitly
$response = $client->queryUsers(new Models\QueryUsersPayload(
    filterConditions: (object)["name" => (object)['$eq' => "Nick"]],
));

response, err := client.QueryUsers(ctx, &getstream.QueryUsersRequest{
  Payload: &getstream.QueryUsersPayload{
    FilterConditions: map[string]interface{}{
      "name":  "Nick",
      "teams": map[string]interface{}{"$in": []string{"red", "blue"}},
    },
  },
})

// search for users that are not part of any team
response, err = client.QueryUsers(ctx, &getstream.QueryUsersRequest{
  Payload: &getstream.QueryUsersPayload{
    FilterConditions: map[string]interface{}{
      "teams": nil,
    },
  },
})

// Server side usage, it searches all teams implicitly
await client.QueryUsersAsync(new QueryUsersPayload
{
    FilterConditions = new Dictionary<string, object>
    {
        { "name", new Dictionary<string, string> { { "$eq", "Nick" } } },
    },
});

client.queryUsers(
  QueryUsersRequest.builder()
    .Payload(
      QueryUsersPayload.builder()
        .filterConditions(
          Map.of("name", "Nick", "teams", Map.of("$in", List.of("red", "blue"))
        )
        .build()
    )
    .build()
).execute();

Querying team resources

Query endpoints follow the same rule. When using multi-tenant, client-side queries will only return channels or calls that match the query and are on the same team as the user. The API injects filter {team: {$in: [<user_teams>]}} for every request that doesn't already contain a filter for the team field. If you want to query across all teams, you have to provide an empty filter like this: {team:{}}. For server-side requests, this filter does not apply.

Querying chat channels

// query all channels from teams that user is a part of
await client.queryChannels({});

// query all channels from all teams
await client.queryChannels({ team: {} });

// query all channels with no teams
await client.queryChannels({ team: { $eq: null } });

// query all channels from teams that user is a part of
val filter = Filters.and(
    Filters.eq("type", "messaging"),
    Filters.`in`("members", listOf(userId)),
)

// query all channels from all teams
val filter = Filters.eq("team", emptyMap<Any, Any>())

client.queryChannels(QueryChannelsRequest(filter = filter, limit = 25)).enqueue()

// query all channels from teams that user is a part of
await client.queryChannels(filter: Filter.empty());

// query all channels from all teams
await client.queryChannels(filter: Filter.custom(key: 'team', value: {}));

// query all channels from teams that user is a part of
Client->QueryChannels();

// query all channels from all teams
Client->QueryChannels(FFilter::Empty(TEXT("team")));

require 'getstream_ruby'
Models = GetStream::Generated::Models

# query all channels from teams that user is a part of
client.chat.query_channels(Models::QueryChannelsRequest.new(
  filter_conditions: {}
))

# query all channels from all teams
client.chat.query_channels(Models::QueryChannelsRequest.new(
  filter_conditions: { 'team' => {} }
))

// query all channels from teams that user is a part of
$response = $client->queryChannels(new Models\QueryChannelsRequest(
    filterConditions: (object)[],
));

// query all channels from all teams
$response = $client->queryChannels(new Models\QueryChannelsRequest(
    filterConditions: (object)["team" => (object)[]],
));

resp, err := client.Chat().QueryChannels(ctx, &getstream.QueryChannelsRequest{
  FilterConditions: map[string]any{},
})

// query all channels from all teams
resp, err = client.Chat().QueryChannels(ctx, &getstream.QueryChannelsRequest{
  FilterConditions: map[string]any{
    "team": map[string]string{},
  },
})

// query all channels from teams that user is a part of
await chat.QueryChannelsAsync(new QueryChannelsRequest
{
    FilterConditions = new Dictionary<string, object>(),
});

// query all channels from all teams
await chat.QueryChannelsAsync(new QueryChannelsRequest
{
    FilterConditions = new Dictionary<string, object>
    {
        { "team", new Dictionary<string, string>() },
    },
});

// query all channels from teams that user is a part of
chat.queryChannels(QueryChannelsRequest.builder()
    .filterConditions(Map.of())
    .build()).execute();

// query all channels from all teams
chat.queryChannels(QueryChannelsRequest.builder()
    .filterConditions(Map.of("team", Map.of()))
    .build()).execute();

Querying video calls

// All calls
client.video.queryCalls();

// Calls without team
client.video.queryCalls({
  filter_conditions: {
    team: null,
  },
});

// Calls with specific team
client.video.queryCalls({
  filter_conditions: {
    team: "blue",
  },
});

# query calls by team field
response = client.video.query_calls(
    filter_conditions={"id": call_id, "team": {"$eq": "blue"}}
)

# retrieve calls without a team
response = client.video.query_calls(
    filter_conditions={"id": call_id, "team": {"$eq": "blue"}}
)

response, err := client.Video().QueryCalls(ctx, &getstream.QueryCallsRequest{
  FilterConditions: &map[string]interface{}{
    "id":   call_id,
    "team": map[string]interface{}{"$eq": "blue"},
  },
})

// retrieve calls without a team
response, err := client.Video().QueryCalls(ctx, &getstream.QueryCallsRequest{
  FilterConditions: &map[string]interface{}{
    "id":   call_id,
    "team": &map[string]interface{}{"$eq": nil},
  },
})

client.video().queryCalls(
  QueryCallsRequest.builder()
    .filterConditions(Map.of(
      "id", callId,
      "team", Map.of("$eq", "blue")
    ))
    .build()
).execute();

// retrieve calls without a team
client.video().queryCalls(
  QueryCallsRequest.builder()
    .filterConditions(Map.of(
      "id", callId,
      "team", Map.of("$eq", null)
    ))
    .build()
).execute();

# All calls
curl -X POST "https://video.stream-io-api.com/api/v2/video/calls?api_key=${API_KEY}" \
  -H "Authorization: ${TOKEN}" \
  -H "stream-auth-type: jwt"

# Calls without team
curl -X POST "https://video.stream-io-api.com/api/v2/video/calls?api_key=${API_KEY}" \
  -H "Authorization: ${TOKEN}" \
  -H "stream-auth-type: jwt" \
  -H "Content-Type: application/json" \
  -d '{"filter_conditions": {"team": null}}'

# Calls with a specific team
curl -X POST "https://video.stream-io-api.com/api/v2/video/calls?api_key=${API_KEY}" \
  -H "Authorization: ${TOKEN}" \
  -H "stream-auth-type: jwt" \
  -H "Content-Type: application/json" \
  -d '{"filter_conditions": {"team": "blue"}}'

Team based roles

By default a user will be assigned only 1 role (ie. user, admin, etc.). If you would like to have different roles depending on the team the user is part of, you can do so by specifying a separate role per team. This team based role is applicable only on resources that belong to that team. Let's imagine user Jane, she's a user with role user throughout the application, however on team red we would like to give her elevated permissions and give her the admin role. We can do this by updating the user as follows:

await client.upsertUser({
  id: "Jane",
  role: "user",
  teams: ["red", "blue"],
  teams_role: {
    red: "admin",
    blue: "user",
  },
});

from getstream.models import UserRequest

response = client.upsert_users(
    UserRequest(
        id="Jane",
        role="user",
        teams=["red", "blue"],
        teams_role={
            "red": "admin",
            "blue": "user",
        },
    )
)

require 'getstream_ruby'
Models = GetStream::Generated::Models

response = client.common.update_users(Models::UpdateUsersRequest.new(
  users: {
    'Jane' => Models::UserRequest.new(
      id: 'Jane',
      role: 'user',
      teams: ['red', 'blue'],
      custom: { 'teams_role' => { 'red' => 'admin', 'blue' => 'user' } }
    )
  }
))

$client->updateUsers(new Models\UpdateUsersRequest(
    users: ["Jane" => new Models\UserRequest(
        id: "Jane",
        role: "user",
        teams: ["red", "blue"],
        custom: (object)[
            "teams_role" => (object)["red" => "admin", "blue" => "user"],
        ],
    )],
));

response, err := client.UpdateUsers(ctx, &getstream.UpdateUsersRequest{
  Users: map[string]getstream.UserRequest{
    "Jane": {
      ID:    "Jane",
      Role:  getstream.PtrTo("user"),
      Teams: []string{"red", "blue"},
      Custom: map[string]any{
        "teams_role": map[string]string{
          "red":  "admin",
          "blue": "user",
        },
      },
    },
  },
})

await client.UpdateUsersAsync(new UpdateUsersRequest
{
    Users = new Dictionary<string, UserRequest>
    {
        {
            "Jane", new UserRequest
            {
                ID = "Jane",
                Role = "user",
                Teams = new List<string> { "red", "blue" },
                TeamsRole = new Dictionary<string, string>
                {
                    { "red", "admin" },
                    { "blue", "user" },
                },
            }
        },
    },
});

var response = client.updateUsers(UpdateUsersRequest.builder()
    .users(Map.of("Jane", UserRequest.builder()
        .id("Jane")
        .role("user")
        .teams(List.of("red", "blue"))
        .teamsRole(Map.of("red", "admin", "blue", "user"))
        .build()))
    .build()).execute();

If no team based role is set for a team, the system uses the role of the user. For example, user Janet is a member of teams red, blue and orange. She has role user and team based roles { "red": "admin", "blue": "user" }:

• On team red, she will have admin level permissions. This means that on resources that belong to team red, she will have admin level permissions.
• On resources from team blue, she has user level permissions.
• On resources from team orange, she also has user level permissions (because no team role was assigned for this team).

Please be aware team based roles will only work when multitenancy is enabled.

Multi-tenant permissions

By default, for multi-tenant applications, all objects (users, channels, calls and messages) must belong to the same team to be able to interact. Multi-tenant permissions enable overriding that behavior, so that certain users can have permissions to interact with objects on any team. The built-in global_moderator and global_admin roles are designed for this; their grants use -any-team permission IDs such as create-channel-any-team and search-user-any-team.

Granting them works like any other permission; see permissions and roles.

The tables below list the default grants for these roles. The .app scope applies across products; the remaining scopes are the built-in chat channel types.

Scope .app

Scope messaging

Scope livestream

Scope team

Scope commerce

Scope gaming

Team usage statistics

For multi-tenant chat applications, you can query usage statistics broken down by team. This is useful for billing, monitoring, and analytics purposes. The API returns detailed metrics for each team including user counts, message volumes, and activity patterns.

Querying Team Usage Stats

Use the queryTeamUsageStats method to retrieve usage statistics. You can query by month or by a custom date range.

// Query current month's stats
const response = await client.queryTeamUsageStats();

// Query specific month
const response = await client.queryTeamUsageStats({ month: "2024-01" });

// Query date range
const response = await client.queryTeamUsageStats({
  start_date: "2024-01-01",
  end_date: "2024-01-31",
});

// With pagination
const response = await client.queryTeamUsageStats({ limit: 10 });
if (response.next) {
  const nextPage = await client.queryTeamUsageStats({
    limit: 10,
    next: response.next,
  });
}

# Query current month's stats
response = client.chat.query_team_usage_stats()

# Query specific month
response = client.chat.query_team_usage_stats(month="2024-01")

# Query date range
response = client.chat.query_team_usage_stats(
    start_date="2024-01-01",
    end_date="2024-01-31"
)

# With pagination
response = client.chat.query_team_usage_stats(limit=10)
if response.data.next:
    next_page = client.chat.query_team_usage_stats(limit=10, next=response.data.next)

require 'getstream_ruby'
Models = GetStream::Generated::Models

# Query current month's stats
response = client.chat.query_team_usage_stats(Models::QueryTeamUsageStatsRequest.new)

# Query specific month
response = client.chat.query_team_usage_stats(Models::QueryTeamUsageStatsRequest.new(
  month: '2024-01'
))

# Query date range
response = client.chat.query_team_usage_stats(Models::QueryTeamUsageStatsRequest.new(
  start_date: '2024-01-01',
  end_date: '2024-01-31'
))

# With pagination
response = client.chat.query_team_usage_stats(Models::QueryTeamUsageStatsRequest.new(limit: 10))
if response.next
  next_page = client.chat.query_team_usage_stats(Models::QueryTeamUsageStatsRequest.new(
    limit: 10,
    next: response.next
  ))
end

// Query current month's stats
$response = $client->queryTeamUsageStats(new Models\QueryTeamUsageStatsRequest());

// Query current month's stats
response, err := client.Chat().QueryTeamUsageStats(ctx, &getstream.QueryTeamUsageStatsRequest{})

// Query specific month
response, err = client.Chat().QueryTeamUsageStats(ctx, &getstream.QueryTeamUsageStatsRequest{
    Month: getstream.PtrTo("2024-01"),
})

// Query date range
response, err = client.Chat().QueryTeamUsageStats(ctx, &getstream.QueryTeamUsageStatsRequest{
    StartDate: getstream.PtrTo("2024-01-01"),
    EndDate:   getstream.PtrTo("2024-01-31"),
})

// With pagination
response, err = client.Chat().QueryTeamUsageStats(ctx, &getstream.QueryTeamUsageStatsRequest{
    Limit: getstream.PtrTo(10),
})
if response.Data.Next != nil && *response.Data.Next != "" {
    nextPage, err := client.Chat().QueryTeamUsageStats(ctx, &getstream.QueryTeamUsageStatsRequest{
        Limit: getstream.PtrTo(10),
        Next:  response.Data.Next,
    })
    _ = nextPage
    _ = err
}

// Query current month's stats
var response = await statsClient.QueryTeamUsageStatsAsync();

// Query specific month
var response = await statsClient.QueryTeamUsageStatsAsync(new QueryTeamUsageStatsOptions
{
    Month = "2024-01"
});

// Query date range
var response = await statsClient.QueryTeamUsageStatsAsync(new QueryTeamUsageStatsOptions
{
    StartDate = "2024-01-01",
    EndDate = "2024-01-31"
});

// With pagination
var response = await statsClient.QueryTeamUsageStatsAsync(new QueryTeamUsageStatsOptions
{
    Limit = 10
});
if (!string.IsNullOrEmpty(response.Next))
{
    var nextPage = await statsClient.QueryTeamUsageStatsAsync(new QueryTeamUsageStatsOptions
    {
        Limit = 10,
        Next = response.Next
    });
}

// Query current month's stats
var response = chat.queryTeamUsageStats(QueryTeamUsageStatsRequest.builder()
    .build()).execute().getData();

// Query specific month
var monthlyResponse = chat.queryTeamUsageStats(QueryTeamUsageStatsRequest.builder()
    .month("2024-01")
    .build()).execute().getData();

// Query date range
var rangeResponse = chat.queryTeamUsageStats(QueryTeamUsageStatsRequest.builder()
    .startDate("2024-01-01")
    .endDate("2024-01-31")
    .build()).execute().getData();

// With pagination
var pageResponse = chat.queryTeamUsageStats(QueryTeamUsageStatsRequest.builder()
    .limit(10)
    .build()).execute().getData();
if (pageResponse.getNext() != null) {
    var nextPage = chat.queryTeamUsageStats(QueryTeamUsageStatsRequest.builder()
        .limit(10)
        .next(pageResponse.getNext())
        .build()).execute().getData();
}

Available Metrics

The response includes statistics for each team with the following metrics:

Metric Attribution

Message metrics (messages_*) are attributed based on the channel's team field (channel.team), while user metrics (users_*) are attributed based on the user's teams array (user.teams). This means you may see messages under a team even when users_* metrics are zero for that team, if messages were sent in channels belonging to that team by users who are not members of that team.

Empty Team

The API returns a row for team="" (empty string) which represents users and messages that are not assigned to any team. This includes messages in channels without a team set and users without any team membership.

Response Modes

The response shape differs based on query mode:

Monthly mode (using month parameter): Returns only the total/aggregated values for each metric. Daily breakdown arrays are omitted.

Daily mode (using start_date and end_date): Returns both daily breakdown arrays and aggregated totals. The aggregation method depends on the metric type:

• SUM: Daily activity metrics (users_daily, messages_daily, translations_daily, image_moderations_daily) - totals are summed across the date range
• MAX: Peak metrics (concurrent_users, concurrent_connections) - totals reflect the maximum value observed
• LATEST: Rolling/cumulative metrics (users_total, users_last_24_hours, users_last_30_days, users_month_to_date, users_engaged_last_30_days, users_engaged_month_to_date, messages_total, messages_last_24_hours, messages_last_30_days, messages_month_to_date) - totals reflect the most recent value

Pagination

Results are paginated in lexicographic order by team name. The next cursor in the response is a base64-encoded team ID. Use this cursor value in subsequent requests to fetch the next page of results. The limit parameter is capped at 30 teams per request.

Date Range Validation

When using custom date ranges, the following validations apply:

• end_date must be greater than or equal to start_date
• The date range cannot exceed 365 days