> ## 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. # Retrieve an identity > Retrieves detailed information about a specific identity using their identity ID or external ID from your system. ## OpenAPI ````yaml get /v2/identities/{id} 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: - description: List models available through the AI Router. name: Models - name: Guardrail Rules - name: Policies - name: Routing Rules - name: API keys description: >- API keys authenticate programmatic access to the workspace. The unified key model exposes opaque tokens, per-domain access grants, and budget / rate-limit constraints (see ADR 0001 and ADR 0002). - name: Budgets description: >- Budgets govern spend, token usage, and request rate across six scopes: workspace, project, identity, api-key, provider, and model. A budget is hierarchical and defense-in-depth — every applicable budget is a hard gate, and the most restrictive one wins per dimension (see ADR 0007). - name: Documentation description: >- Search the orq.ai documentation. Proxies the workspace's query to the hosted docs search index. - name: Files description: File upload and retrieval operations. - name: Identities description: >- Identities represent end users from your system for usage and engagement tracking. - name: Projects description: Projects organize resources within a workspace - name: Skills description: >- Skills are modular instructions you can use to codify processes and conventions - name: Responses - description: >- Run agents on a cadence — cron, interval, or one-off. Minimum firing interval is 1 hour. name: Agent Schedules - name: Embeddings - 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. externalDocs: url: https://docs.orq.ai description: orq.ai Documentation paths: /v2/identities/{id}: get: tags: - Identities summary: Retrieve an identity description: >- Retrieves detailed information about a specific identity using their identity ID or external ID from your system. operationId: RetrieveIdentity parameters: - name: id in: path description: Identity ID to retrieve. required: true schema: type: string - name: include_metrics in: query description: Include aggregate usage metrics on the returned identity. schema: type: boolean responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/RetrieveIdentityResponse' x-code-samples: - lang: curl label: Core - Retrieve identity with metrics source: | curl --get 'https://api.orq.ai/v2/identities/customer_12345' \ --header 'Authorization: Bearer $ORQ_API_KEY' \ --data-urlencode 'include_metrics=true' - lang: python label: Python - Retrieve identity with metrics source: | import os from orq_ai_sdk import Orq client = Orq(api_key=os.environ["ORQ_API_KEY"]) result = client.identities.retrieve( id="customer_12345", include_metrics=True, ) print(result.identity.display_name) print(result.identity.metrics.total_requests) - lang: typescript label: Node.js - Retrieve identity with metrics source: | import { Orq } from '@orq-ai/node'; const client = new Orq({ apiKey: process.env.ORQ_API_KEY, }); const result = await client.identities.retrieve({ id: 'customer_12345', includeMetrics: true, }); console.log(result.identity.displayName); console.log(result.identity.metrics.totalRequests); components: schemas: RetrieveIdentityResponse: required: - identity type: object properties: identity: allOf: - $ref: '#/components/schemas/Identity' description: Requested identity. Identity: required: - _id - external_id - workspace_id - created - updated type: object properties: _id: type: string description: |- Unique identity identifier assigned by ORQ. Returned as `_id` for compatibility with the v1 identity API. external_id: type: string description: |- Customer-provided stable identifier for this identity. This value is required on create and is unique within the workspace. workspace_id: type: string description: Workspace that owns the identity. display_name: type: string description: Human-readable display name for the identity. email: type: string description: Email address associated with the identity. avatar_url: type: string description: URL of the identity avatar image. tags: type: array items: type: string description: Free-form labels used to organize and filter identities. metadata: type: object description: Custom JSON metadata stored with the identity. created: type: string description: ISO timestamp for when the identity was created. updated: type: string description: ISO timestamp for when the identity was last updated. metrics: allOf: - $ref: '#/components/schemas/IdentityMetrics' description: |- Optional usage and cost metrics. Present only when requested with `include_metrics`. IdentityMetrics: required: - total_tokens - total_cost - total_requests - error_rate type: object properties: total_tokens: type: number description: Total token count attributed to the identity. format: double total_cost: type: number description: Total cost attributed to the identity. format: double total_requests: type: number description: Total request count attributed to the identity. format: double error_rate: type: number description: Fraction of attributed requests that failed. format: double securitySchemes: ApiKey: type: http scheme: bearer bearerFormat: JWT ````