---
title: "GET /v2/users"
method: GET
path: "/v2/users"
tags: ["Social"]
---

# GET /v2/users

`GET /v2/users`

## Request

- Base URL: `https://api.arbital.xyz` (the document declares no server; this is the origin it was published from)
- URL: `https://api.arbital.xyz/v2/users`
- Auth: HTTP bearer

Searches active Arbital profiles by username prefix. A conventional leading @ is accepted and ignored. context=mention requires authentication and returns compact native targets without holdings/counts. It accepts a 1–30 ASCII username prefix after one optional @, defaults to 10 results (maximum 20), and uses a strict viewer/prefix-bound cursor of at most 512 bytes. Current status and bilateral blocks apply before LIMIT. Ordinary search remains unchanged.

## Query parameters

- `query` string, required
- `limit` integer
- `cursor` string
- `context` 'mention'

## Response `200`

Matching public profiles

- union
  - PublicProfilePage
    - `next_cursor` string, nullable, required
    - `users` PublicProfile[], required
      - `bio` string, nullable, required
      - `display_name` string, nullable, required
      - `follower_count` integer, required
      - `following_count` integer, required
      - `follows_viewer` boolean, required
      - `cover_image_url` string, nullable, required: Reserved for a future moderated cover-image capability; currently null.
      - `profile_image_url` string, uri, nullable, required: Backend-owned URL for the approved profile image or the user's stable CALLD default avatar.
      - `user_id` string, uuid, required
      - `username` string, required
      - `viewer_follows` boolean, required
      - `x_account` PublicXAccount, required
        - `avatar_url` string, nullable, required
        - `display_name` string, nullable, required
        - `username` string, required
  - NativeMentionSearchPage
    - `users` NativeMentionSearchResult[], required
      - `user_id` string, uuid, required
      - `username` string, required
      - `display_name` string, nullable, required
      - `profile_image_url` string, nullable, required
      - `mention_target` NativeMentionTarget, required
        - `kind` 'early_user', required
        - `user_id` string, uuid, required
      - `profile_target` NativeMentionTarget, required
        - `kind` 'early_user', required
        - `user_id` string, uuid, required
      - `mention_eligible` true, required
      - `notification_supported` true, required
    - `next_cursor` string, nullable, required

## Other responses

- `400`: Stable machine-readable private social problem
- `401`: Stable machine-readable private social problem
- `408`: Stable machine-readable private social problem
- `409`: Stable machine-readable private social problem
- `413`: Stable machine-readable private social problem
- `429`: Per-principal or anonymous-peer social request budget exhausted
- `503`: Stable machine-readable private social problem

---

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