---
title: "List users"
method: GET
path: "/v1/users"
tags: ["Users"]
---

# List users

`GET /v1/users`

Retrieve all members of your workspace. Returns each user's profile information including name, email, job title, role, and admin status.

Results can be filtered by name or email and sorted by creation date or name. They are paginated.

> 🚧 Permissions
>
> Please check you have the relevant permissions required to access this resource. This may include specific permissions on the object itself or its parent, or having the correct user role if you're making updates.

## Query parameters

- `page` object
  - `start_cursor` string
  - `limit` integer, nullable
- `filter` object
  - `name` object — Filter results based on string value. You can either provide a `contains` operator for substring matching or an `equal_to` operator for exact matching. These options are mutually exclusive.
    - `contains` string — Substring (case-insensitive) to search for within the target string
    - `equal_to` string — Equal to operator
  - `email` object — Filter results based on string value. You can either provide a `contains` operator for substring matching or an `equal_to` operator for exact matching. These options are mutually exclusive.
    - `contains` string — Substring (case-insensitive) to search for within the target string
    - `equal_to` string — Equal to operator
- `sort` union
  - 'created_at:asc' | 'created_at:desc' | 'name:asc' | 'name:desc'
  - string[]

## Response `200`

200

- object
  - `data` object[], required
    - `id` string, required
    - `url` string — The URL of this user in the Dovetail web app.
    - `name` string, nullable, required
    - `email` string, nullable, required
    - `job_title` string, nullable, required
    - `role` 'CONTRIBUTOR' | 'MANAGER' | 'VIEWER', nullable, required
    - `workspace_admin` boolean, required
    - `created_at` string, required
    - `updated_at` string, required
  - `page` object, required
    - `total_count` number, required — Total number of items matching the query.
    - `has_more` boolean, required — Whether there are more items beyond the current page.
    - `next_cursor` string, nullable, required — Cursor to pass as `page[start_cursor]` to fetch the next page. Null when there are no more results.

## Other responses

- `400` — 400
- `401` — 401
- `403` — 403
- `404` — 404
- `422` — 422
- `429` — 429
- `500` — 500

---

[API](https://skmtc.net/dovetail/apis/dovetail-public-api.md) · [All operations](https://skmtc.net/dovetail/apis/dovetail-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/dovetail/dovetail-public-api/revisions/4107f5fdf8b2/schema)