---
title: "Bulk Create Users Route"
method: POST
path: "/management/v1/users/bulk"
tags: ["Internal User management"]
---

# Bulk Create Users Route

`POST /management/v1/users/bulk`

Create up to 500 internal users in one request, optionally adding each one to teams.

Every entry in `users` takes the same fields as `/user/new`, with two differences: `auto_create_key`
defaults to `false` (opt in per user to also get a virtual key back) and `send_invite_email` is not
supported. Unknown fields are rejected with 422. Rows are validated together (duplicate ids or emails,
unknown teams, roles the caller may not grant), inserted in one statement, and each referenced team is
written once for all of its new members.

Rows fail independently: a bad row is reported in `data` with `success: false` and an `error`, and the
other rows still get created. A user that was created but could not be added to one of its teams is
reported with `success: true`, `teams` listing where they did land, and `error` naming the failed team.
The whole request is refused with a 403 problem document only if creating the valid rows would exceed
the license seat limit.

Example curl:
```
curl -X POST "http://localhost:4000/management/v1/users/bulk" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-1234" \
-d '{
    "users": [
        {"user_email": "a@example.com", "user_role": "internal_user", "teams": ["team-1"]},
        {"user_email": "b@example.com", "user_role": "internal_user", "auto_create_key": true}
    ]
}'
```

Returns `data` (one entry per input row, in order, with `user_id`, `user_email`, `success`, `teams`,
`key`, `error`) and `meta` with `total_requested`, `created` and `failed`.

## Request body

- BulkNewUserRequest
  - `users` BulkNewUserItem[], required
    - `key_alias` string, nullable
    - `duration` string, nullable
    - `models` unknown[], nullable
      - unknown
    - `spend` number, nullable
    - `max_budget` number, nullable
    - `user_id` string, nullable
    - `team_id` string, nullable
    - `agent_id` string, nullable
    - `max_parallel_requests` integer, nullable
    - `metadata` object, nullable
    - `tpm_limit` integer, nullable
    - `rpm_limit` integer, nullable
    - `budget_duration` string, nullable
    - `budget_limits` BudgetLimitEntry[], nullable
      - `budget_duration` string, required
      - `max_budget` number, required
      - `reset_at` string, date-time, nullable
    - `allowed_cache_controls` unknown[], nullable
      - unknown
    - `config` object, nullable
    - `permissions` object, nullable
    - `model_max_budget` object, nullable
    - `budget_fallbacks` object, nullable
    - `model_rpm_limit` object, nullable
    - `model_tpm_limit` object, nullable
    - `mcp_rpm_limit` object, nullable
    - `tag_rpm_limit` object, nullable
    - `guardrails` string[], nullable
    - `policies` string[], nullable
    - `prompts` string[], nullable
    - `blocked` boolean, nullable
    - `aliases` object, nullable
    - `object_permission` LiteLLMObjectPermissionBase
      - `mcp_servers` string[], nullable
      - `mcp_access_groups` string[], nullable
      - `mcp_tool_permissions` object, nullable
      - `mcp_toolsets` string[], nullable
      - `blocked_tools` string[], nullable
      - `vector_stores` string[], nullable
      - `agents` string[], nullable
      - `agent_access_groups` string[], nullable
      - `models` string[], nullable
      - `search_tools` string[], nullable
      - `mcp_tool_search_enabled` boolean, nullable
      - `skills` string[], nullable
    - `user_email` string, nullable
    - `user_alias` string, nullable
    - `user_role` 'proxy_admin' | 'proxy_admin_viewer' | 'internal_user' | 'internal_user_viewer', nullable
    - `teams` union
      - string[]
      - NewUserRequestTeam[]
        - `team_id` string, required
        - `max_budget_in_team` number, nullable
        - `user_role` 'user' | 'admin'
    - `auto_create_key` boolean
    - `send_invite_email` boolean, nullable
    - `sso_user_id` string, nullable
    - `organizations` string[], nullable

## Response `200`

Successful Response

- BulkNewUserResponse — `data` holds one result per input row, in input order.
  - `data` UserCreateResult[], required
    - `user_id` string, nullable
    - `user_email` string, nullable
    - `success` boolean, required
    - `teams` string[], nullable
    - `key` string, nullable
    - `error` string, nullable
  - `meta` BulkNewUserMeta, required
    - `total_requested` integer, required
    - `created` integer, required
    - `failed` integer, required

## Other responses

- `422` — Validation Error

## Changes

- **2026-09-30** `85ac4287140e` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/flock/apis/litellm-api/changes/management/v1/users/bulk/post.md)

---

[API](https://skmtc.dev/flock/apis/litellm-api.md) · [All operations](https://skmtc.dev/flock/apis/litellm-api/llms.txt) · [OpenAPI document](https://skmtc.dev/flock/apis/litellm-api/revisions/ee3a9ebe33fd?raw)