---
title: "Get sub users"
method: GET
path: "/sub_user/list"
tags: ["Sub Users"]
---

# Get sub users

`GET /sub_user/list`

Retrieves the sub users the calling user may manage: every sub user in the account for an administrator, only the caller's own sub users otherwise. Sub users themselves are refused entirely.

## Query parameters

- `parent_user_id` Id — unresolved $ref

## Response `200`

OK

- object
  - `sub_users` SubUser[], required
    - `id` integer, required — unique identifier of the sub user
    - `apikey_count` integer, required — how many live API keys (enabled, unexpired, and excluding internal delegation keys) the sub user owns
    - `assigned_policies` SubUserPolicy[], required — the policies assigned to the sub user itself
      - `id` integer, required — unique identifier of the policy
      - `name` string, required — the name of the policy
    - `connector_display_name` string, nullable, required — the display name of the Connector the sub user was issued for, exactly as the client sent it at issuance. `null` when issuance carried none, and `null` once neither the grant nor any token that carried it remains
    - `created_at` string, date-time, required — when the sub user was created
    - `effective_policies` SubUserPolicy[], required — the policies the sub user can actually exercise: its assigned policies minus anything its parent user does not hold itself
      - `id` integer, required — unique identifier of the policy
      - `name` string, required — the name of the policy
    - `email` string, required — the synthetic, non-deliverable email of the sub user
    - `last_used_at` string, date-time, nullable, required — when the sub user was last active, to a resolution of one hour. Both a use of any credential it holds and a job it ran count, since a sub user behind a schedule may never present a credential of its own. Set to the creation time for a sub user that has never been active, and `null` when the last use is unknown because the tracking record is missing
    - `name` string, required — the display name of the sub user, composed at issuance as `<owner name> (agent: <Connector display name>)`, or `<owner name> (agent)` when issuance carried no Connector display name. The Connector display name is collapsed onto a single line and truncated to 100 characters, as is the owner name, and a truncated part ends in an ellipsis. The name is composed once and does not follow a later change to either half: renaming the Connector, or the owner renaming themselves, leaves it as it was at issuance. An account administrator may overwrite it, and the sub user itself may not. Sub users issued before td-api started composing names carry their synthetic email address here instead
    - `oauth_token_count` integer, required — how many unrevoked OAuth access tokens the sub user owns; an expired token counts until it is revoked
    - `parent_user` union, required — the user the sub user derives from. `null` when the parent link no longer resolves
      - object, nullable
      - SubUserParentReference — Minimal information on the parent user of a sub user
        - `id` integer, required — unique identifier of the user
        - `email` string, required — the email of the user
        - `name` string, required — the display name of the user

## Changes

- **2026-08-31** `fb9de609df98` — 1 breaking, 3 info
  - removed the required property `sub_users/items/credential_count` from the response with the `200` status
  - added the required property `sub_users/items/apikey_count` to the response with the `200` status
  - added the required property `sub_users/items/last_used_at` to the response with the `200` status
  - added the required property `sub_users/items/oauth_token_count` to the response with the `200` status
- **2026-08-26** `a6bfa4c037ac` — 1 info
  - added the new optional `query` request parameter `parent_user_id`
- **2026-08-20** `c62cee341b93` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/treasure/apis/treasure-data-api/changes/sub_user/list/get.md)

---

[API](https://skmtc.dev/treasure/apis/treasure-data-api.md) · [All operations](https://skmtc.dev/treasure/apis/treasure-data-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/treasure/treasure-data-api/revisions/fb9de609df98/schema)