> ## Documentation Index > Fetch the complete documentation index at: https://docs.orq.ai/llms.txt > Use this file to discover all available pages before exploring further. # List identities > Retrieves a paginated list of identities in your workspace. Use pagination parameters to navigate through large identity lists efficiently. ## OpenAPI ````yaml get /v2/identities openapi: 3.1.0 info: title: orq.ai API version: '2.0' description: orq.ai API documentation servers: - url: https://api.orq.ai security: - ApiKey: [] tags: - name: Guardrail Rules - name: Policies - name: Routing Rules - name: Files description: File upload and retrieval operations. - name: FilesService - name: Projects description: Projects organize resources within a workspace - name: ProjectsService - name: Skills description: >- Skills are modular instructions you can use to codify processes and conventions - name: SkillsService - name: Responses - description: >- Run agents on a cadence — cron, interval, or one-off. Minimum firing interval is 1 hour. name: Agent Schedules - name: Reporting description: >- GenAI reporting API over canonical analytics rollups. Accepts a metric name, time range, grain, group-by, and filters; returns a typed time series and optional totals. - name: ReportingService description: |- ReportingService exposes a single QueryReport RPC that maps allowlisted analytics payloads onto safe rollup queries. Callers never send SQL; the backend picks the rollup family and grain from the metric catalogue, the requested range, and the requested grouping. externalDocs: url: https://docs.orq.ai description: orq.ai Documentation paths: /v2/identities: get: tags: - Identities summary: List identities description: >- Retrieves a paginated list of identities in your workspace. Use pagination parameters to navigate through large identity lists efficiently. operationId: ListIdentities parameters: - schema: type: integer minimum: 1 maximum: 50 default: 10 description: >- A limit on the number of objects to be returned. Limit can range between 1 and 50, and the default is 10 required: false description: >- A limit on the number of objects to be returned. Limit can range between 1 and 50, and the default is 10 name: limit in: query - schema: type: string description: >- A cursor for use in pagination. `starting_after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, ending with `01JJ1HDHN79XAS7A01WB3HYSDB`, your subsequent call can include `after=01JJ1HDHN79XAS7A01WB3HYSDB` in order to fetch the next page of the list. required: false description: >- A cursor for use in pagination. `starting_after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, ending with `01JJ1HDHN79XAS7A01WB3HYSDB`, your subsequent call can include `after=01JJ1HDHN79XAS7A01WB3HYSDB` in order to fetch the next page of the list. name: starting_after in: query - schema: type: string description: >- A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, starting with `01JJ1HDHN79XAS7A01WB3HYSDB`, your subsequent call can include `before=01JJ1HDHN79XAS7A01WB3HYSDB` in order to fetch the previous page of the list. required: false description: >- A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, starting with `01JJ1HDHN79XAS7A01WB3HYSDB`, your subsequent call can include `before=01JJ1HDHN79XAS7A01WB3HYSDB` in order to fetch the previous page of the list. name: ending_before in: query - schema: type: string description: >- Search identities by display name or email address. Minimum 2 characters required. example: john required: false description: >- Search identities by display name or email address. Minimum 2 characters required. name: search in: query - schema: type: object properties: tags: type: array items: type: string description: >- Filter identities by tags. Can be provided as JSON object {"tags": ["premium", "beta-user"]} or as query format "tags=premium,beta-user" example: tags: - premium - beta-user required: false description: >- Filter identities by tags. Can be provided as JSON object {"tags": ["premium", "beta-user"]} or as query format "tags=premium,beta-user" name: filter_by in: query - schema: type: - boolean - 'null' default: false description: Include usage metrics of the last 30 days for each identity. required: false description: Include usage metrics of the last 30 days for each identity. name: include_metrics in: query responses: '200': description: List of identities content: application/json: schema: type: object properties: object: type: string enum: - list data: type: array items: type: object properties: _id: type: string format: ulid description: >- Unique ULID (Universally Unique Lexicographically Sortable Identifier) for the contact example: contact_01ARZ3NDEKTSV4RRFFQ69G5FAV external_id: type: string minLength: 1 maxLength: 120 description: >- Unique string value to identify the contact user in the customer's system. This should be the same ID you use in your system to reference this user. example: user_12345 display_name: type: - string - 'null' description: >- Display name or nickname of the contact user. This is typically shown in user interfaces. example: Jane Smith email: type: - string - 'null' format: email description: Email address of the contact user example: jane.smith@example.com avatar_url: type: - string - 'null' format: uri description: URL linking to the contact user's avatar image example: https://example.com/avatars/jane-smith.jpg tags: type: array items: type: string description: >- Array of tags associated with the contact. Useful for organizing and filtering contacts by categories, departments, or custom classifications. example: - premium - beta-user - enterprise metadata: type: object additionalProperties: {} description: >- Additional custom metadata associated with the contact as key-value pairs. Use this to store any extra information specific to your application. example: department: Engineering role: Senior Developer subscription_tier: premium last_login: '2024-01-15T10:30:00Z' created: anyOf: - format: date-time type: string - format: date-time type: string default: '2026-05-14T21:19:47.506Z' readOnly: true format: date-time description: The date and time the resource was created updated: anyOf: - type: string format: date-time default: '2026-05-14T21:19:47.508Z' - format: date-time type: string readOnly: true format: date-time description: The date and time the resource was last updated metrics: type: object properties: total_cost: type: number description: Total cost in dollars of the last 30 days example: 100 total_tokens: type: number description: Total tokens of the last 30 days example: 1000 total_requests: type: number description: Total requests of the last 30 days example: 1000 error_rate: type: number description: P50 error rate of the last 30 days example: 22 required: - total_cost - total_tokens - total_requests - error_rate required: - _id - external_id - metrics has_more: type: boolean required: - object - data - has_more example: data: - _id: contact_01ARZ3NDEKTSV4RRFFQ69G5FAV external_id: user_12345 display_name: Jane Smith email: jane.smith@example.com avatar_url: https://example.com/avatars/jane-smith.jpg tags: - premium - beta-user metadata: department: Engineering role: Senior Developer created: '2024-01-15T10:30:00Z' updated: '2024-01-15T10:30:00Z' - _id: contact_01ARZ3NDEKTSV4RRFFQ69G5XY external_id: user_67890 display_name: John Doe email: john.doe@example.com tags: - enterprise metadata: department: Sales role: Account Manager created: '2024-01-14T09:15:00Z' updated: '2024-01-14T09:15:00Z' has_more: false x-code-samples: - lang: typescript label: Node.js source: |- import { Orq } from "@orq-ai/node"; const orq = new Orq({ apiKey: process.env["ORQ_API_KEY"] }); const identities = await orq.identities.list({ limit: 50, search: "john", startingAfter: "contact_01ARZ3NDEKTSV4RRFFQ69G5FAV" }); console.log(identities.data); console.log('Has more:', identities.hasMore); - lang: python label: Python source: |- from orq_ai_sdk import Orq import os orq = Orq(api_key=os.getenv("ORQ_API_KEY")) identities = orq.identities.list( limit=50, search="john", starting_after="contact_01ARZ3NDEKTSV4RRFFQ69G5FAV" ) print(identities.data) print(f"Has more: {identities.has_more}") components: securitySchemes: ApiKey: type: http scheme: bearer bearerFormat: JWT ````