> ## 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.

# Identities SDK Reference

> SDK reference for the Identities API, available in Node.js and Python.

## Identities

### List Identities

Retrieves a paginated list of identities in your workspace. Use pagination parameters to navigate through large identity lists efficiently.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.identities.list(limit=10, search="john", include_metrics=False)

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.identities.list({
      limit: 10,
      search: "john",
      includeMetrics: false,
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "limit": Optional[int],
        "starting_after": Optional[str],
        "ending_before": Optional[str],
        "search": Optional[str],
        "filter_by_tags": List[str],
        "include_metrics": Optional[bool],
        "sort_by": Optional[Literal["IDENTITY_SORT_FIELD_UNSPECIFIED", "IDENTITY_SORT_FIELD_DISPLAY_NAME", "IDENTITY_SORT_FIELD_UPDATED"]],
        "include_budget": Optional[bool],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      limit?: number;
      startingAfter?: string;
      endingBefore?: string;
      search?: string;
      filterByTags?: string[];
      includeMetrics?: boolean;
      sortBy?: string;
      includeBudget?: boolean;
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "object": str,
        "data": {
            "id": str,
            "external_id": str,
            "workspace_id": str,
            "display_name": Optional[str],
            "email": Optional[str],
            "avatar_url": Optional[str],
            "tags": List[str],
            "metadata": {},  # optional
            "created": str,
            "updated": str,
            "metrics": {  # optional
                "total_tokens": float,
                "total_cost": float,
                "total_requests": float,
                "error_rate": float,
            },
            "budget": {  # optional
                "budget_id": Optional[str],
                "scope": {  # optional
                    "workspace": {},  # optional
                    "project": {  # optional
                        "project_id": Optional[str],
                    },
                    "identity": {  # optional
                        "identity_external_id": Optional[str],
                    },
                    "api_key": {  # optional
                        "api_key_id": Optional[str],
                    },
                    "provider": {  # optional
                        "provider": Optional[str],
                    },
                    "model": {  # optional
                        "model_id": Optional[str],
                    },
                },
                "match": {  # optional
                    "cel": Optional[str],
                },
                "limits": {  # optional
                    "period": Optional[Literal["BUDGET_PERIOD_UNSPECIFIED", "BUDGET_PERIOD_DAILY", "BUDGET_PERIOD_WEEKLY", "BUDGET_PERIOD_MONTHLY", "BUDGET_PERIOD_YEARLY", "BUDGET_PERIOD_ONE_TIME"]],
                    "amount": Optional[float],
                    "token_limit": Optional[float],
                },
                "rate_limit": {  # optional
                    "requests_per_minute": Optional[int],
                },
                "is_active": Optional[bool],
                "expires_at": date,
                "created_at": date,
                "updated_at": date,
                "usage": {  # optional
                    "amount": Optional[float],
                    "tokens": Optional[float],
                    "requests": Optional[int],
                },
            },
        },
        "has_more": bool,
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      object: string;
      data: {
        id: string;
        externalId: string;
        workspaceId: string;
        displayName?: string;
        email?: string;
        avatarUrl?: string;
        tags?: string[];
        metadata?: {};
        created: string;
        updated: string;
        metrics?: {
          totalTokens: number;
          totalCost: number;
          totalRequests: number;
          errorRate: number;
        };
        budget?: {
          budgetId?: string;
          scope?: {
            workspace?: {};
            project?: {
              projectId?: string;
            };
            identity?: {
              identityExternalId?: string;
            };
            apiKey?: {
              apiKeyId?: string;
            };
            provider?: {
              provider?: string;
            };
            model?: {
              modelId?: string;
            };
          };
          match?: {
            cel?: string;
          };
          limits?: {
            period?: string;
            amount?: number;
            tokenLimit?: number;
          };
          rateLimit?: {
            requestsPerMinute?: number;
          };
          isActive?: boolean;
          expiresAt?: Date;
          createdAt?: Date;
          updatedAt?: Date;
          usage?: {
            amount?: number;
            tokens?: number;
            requests?: number;
          };
        };
      };
      hasMore: boolean;
    }
    ```
  </CodeGroup>
</Expandable>

### Create an Identity

Creates a new identity with a unique external\_id. If an identity with the same external\_id already exists, the operation will fail.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.identities.create(external_id="<id>")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.identities.create({
      externalId: "<id>",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "external_id": str,  # required
        "display_name": Optional[str],
        "email": Optional[str],
        "avatar_url": Optional[str],
        "tags": List[str],
        "metadata": {},  # optional
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      externalId: string;  // required
      displayName?: string;
      email?: string;
      avatarUrl?: string;
      tags?: string[];
      metadata?: {};
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "identity": {
            "id": str,
            "external_id": str,
            "workspace_id": str,
            "display_name": Optional[str],
            "email": Optional[str],
            "avatar_url": Optional[str],
            "tags": List[str],
            "metadata": {},  # optional
            "created": str,
            "updated": str,
            "metrics": {  # optional
                "total_tokens": float,
                "total_cost": float,
                "total_requests": float,
                "error_rate": float,
            },
            "budget": {  # optional
                "budget_id": Optional[str],
                "scope": {  # optional
                    "workspace": {},  # optional
                    "project": {  # optional
                        "project_id": Optional[str],
                    },
                    "identity": {  # optional
                        "identity_external_id": Optional[str],
                    },
                    "api_key": {  # optional
                        "api_key_id": Optional[str],
                    },
                    "provider": {  # optional
                        "provider": Optional[str],
                    },
                    "model": {  # optional
                        "model_id": Optional[str],
                    },
                },
                "match": {  # optional
                    "cel": Optional[str],
                },
                "limits": {  # optional
                    "period": Optional[Literal["BUDGET_PERIOD_UNSPECIFIED", "BUDGET_PERIOD_DAILY", "BUDGET_PERIOD_WEEKLY", "BUDGET_PERIOD_MONTHLY", "BUDGET_PERIOD_YEARLY", "BUDGET_PERIOD_ONE_TIME"]],
                    "amount": Optional[float],
                    "token_limit": Optional[float],
                },
                "rate_limit": {  # optional
                    "requests_per_minute": Optional[int],
                },
                "is_active": Optional[bool],
                "expires_at": date,
                "created_at": date,
                "updated_at": date,
                "usage": {  # optional
                    "amount": Optional[float],
                    "tokens": Optional[float],
                    "requests": Optional[int],
                },
            },
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      identity: {
        id: string;
        externalId: string;
        workspaceId: string;
        displayName?: string;
        email?: string;
        avatarUrl?: string;
        tags?: string[];
        metadata?: {};
        created: string;
        updated: string;
        metrics?: {
          totalTokens: number;
          totalCost: number;
          totalRequests: number;
          errorRate: number;
        };
        budget?: {
          budgetId?: string;
          scope?: {
            workspace?: {};
            project?: {
              projectId?: string;
            };
            identity?: {
              identityExternalId?: string;
            };
            apiKey?: {
              apiKeyId?: string;
            };
            provider?: {
              provider?: string;
            };
            model?: {
              modelId?: string;
            };
          };
          match?: {
            cel?: string;
          };
          limits?: {
            period?: string;
            amount?: number;
            tokenLimit?: number;
          };
          rateLimit?: {
            requestsPerMinute?: number;
          };
          isActive?: boolean;
          expiresAt?: Date;
          createdAt?: Date;
          updatedAt?: Date;
          usage?: {
            amount?: number;
            tokens?: number;
            requests?: number;
          };
        };
      };
    }
    ```
  </CodeGroup>
</Expandable>

### Retrieve an Identity

Retrieves detailed information about a specific identity using their identity ID or external ID from your system.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.identities.retrieve(id="<id>", include_metrics=False)

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.identities.retrieve({
      id: "<id>",
      includeMetrics: false,
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "id": str,  # required
        "include_metrics": Optional[bool],
        "include_budget": Optional[bool],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id: string;  // required
      includeMetrics?: boolean;
      includeBudget?: boolean;
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "identity": {
            "id": str,
            "external_id": str,
            "workspace_id": str,
            "display_name": Optional[str],
            "email": Optional[str],
            "avatar_url": Optional[str],
            "tags": List[str],
            "metadata": {},  # optional
            "created": str,
            "updated": str,
            "metrics": {  # optional
                "total_tokens": float,
                "total_cost": float,
                "total_requests": float,
                "error_rate": float,
            },
            "budget": {  # optional
                "budget_id": Optional[str],
                "scope": {  # optional
                    "workspace": {},  # optional
                    "project": {  # optional
                        "project_id": Optional[str],
                    },
                    "identity": {  # optional
                        "identity_external_id": Optional[str],
                    },
                    "api_key": {  # optional
                        "api_key_id": Optional[str],
                    },
                    "provider": {  # optional
                        "provider": Optional[str],
                    },
                    "model": {  # optional
                        "model_id": Optional[str],
                    },
                },
                "match": {  # optional
                    "cel": Optional[str],
                },
                "limits": {  # optional
                    "period": Optional[Literal["BUDGET_PERIOD_UNSPECIFIED", "BUDGET_PERIOD_DAILY", "BUDGET_PERIOD_WEEKLY", "BUDGET_PERIOD_MONTHLY", "BUDGET_PERIOD_YEARLY", "BUDGET_PERIOD_ONE_TIME"]],
                    "amount": Optional[float],
                    "token_limit": Optional[float],
                },
                "rate_limit": {  # optional
                    "requests_per_minute": Optional[int],
                },
                "is_active": Optional[bool],
                "expires_at": date,
                "created_at": date,
                "updated_at": date,
                "usage": {  # optional
                    "amount": Optional[float],
                    "tokens": Optional[float],
                    "requests": Optional[int],
                },
            },
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      identity: {
        id: string;
        externalId: string;
        workspaceId: string;
        displayName?: string;
        email?: string;
        avatarUrl?: string;
        tags?: string[];
        metadata?: {};
        created: string;
        updated: string;
        metrics?: {
          totalTokens: number;
          totalCost: number;
          totalRequests: number;
          errorRate: number;
        };
        budget?: {
          budgetId?: string;
          scope?: {
            workspace?: {};
            project?: {
              projectId?: string;
            };
            identity?: {
              identityExternalId?: string;
            };
            apiKey?: {
              apiKeyId?: string;
            };
            provider?: {
              provider?: string;
            };
            model?: {
              modelId?: string;
            };
          };
          match?: {
            cel?: string;
          };
          limits?: {
            period?: string;
            amount?: number;
            tokenLimit?: number;
          };
          rateLimit?: {
            requestsPerMinute?: number;
          };
          isActive?: boolean;
          expiresAt?: Date;
          createdAt?: Date;
          updatedAt?: Date;
          usage?: {
            amount?: number;
            tokens?: number;
            requests?: number;
          };
        };
      };
    }
    ```
  </CodeGroup>
</Expandable>

### Delete an Identity

Permanently deletes an identity from your workspace and cleans up associated budget configurations.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.identities.delete(id="<id>")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.identities.delete({
      id: "<id>",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "id": str,  # required
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id: string;  // required
    }
    ```
  </CodeGroup>
</Expandable>

### Update an Identity

Updates specific fields of an existing identity. Only the fields provided in the request body will be updated.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.identities.update(id="<id>")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.identities.update({
      id: "<id>",
      updateIdentityRequest: {},
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "id": str,  # required
        "display_name": Optional[str],
        "email": Optional[str],
        "avatar_url": Optional[str],
        "tags": List[str],
        "metadata": {},  # optional
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id: string;  // required
      updateIdentityRequest: {  // required
        displayName?: string;
        email?: string;
        avatarUrl?: string;
        tags?: string[];
        metadata?: {};
      };
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "identity": {
            "id": str,
            "external_id": str,
            "workspace_id": str,
            "display_name": Optional[str],
            "email": Optional[str],
            "avatar_url": Optional[str],
            "tags": List[str],
            "metadata": {},  # optional
            "created": str,
            "updated": str,
            "metrics": {  # optional
                "total_tokens": float,
                "total_cost": float,
                "total_requests": float,
                "error_rate": float,
            },
            "budget": {  # optional
                "budget_id": Optional[str],
                "scope": {  # optional
                    "workspace": {},  # optional
                    "project": {  # optional
                        "project_id": Optional[str],
                    },
                    "identity": {  # optional
                        "identity_external_id": Optional[str],
                    },
                    "api_key": {  # optional
                        "api_key_id": Optional[str],
                    },
                    "provider": {  # optional
                        "provider": Optional[str],
                    },
                    "model": {  # optional
                        "model_id": Optional[str],
                    },
                },
                "match": {  # optional
                    "cel": Optional[str],
                },
                "limits": {  # optional
                    "period": Optional[Literal["BUDGET_PERIOD_UNSPECIFIED", "BUDGET_PERIOD_DAILY", "BUDGET_PERIOD_WEEKLY", "BUDGET_PERIOD_MONTHLY", "BUDGET_PERIOD_YEARLY", "BUDGET_PERIOD_ONE_TIME"]],
                    "amount": Optional[float],
                    "token_limit": Optional[float],
                },
                "rate_limit": {  # optional
                    "requests_per_minute": Optional[int],
                },
                "is_active": Optional[bool],
                "expires_at": date,
                "created_at": date,
                "updated_at": date,
                "usage": {  # optional
                    "amount": Optional[float],
                    "tokens": Optional[float],
                    "requests": Optional[int],
                },
            },
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      identity: {
        id: string;
        externalId: string;
        workspaceId: string;
        displayName?: string;
        email?: string;
        avatarUrl?: string;
        tags?: string[];
        metadata?: {};
        created: string;
        updated: string;
        metrics?: {
          totalTokens: number;
          totalCost: number;
          totalRequests: number;
          errorRate: number;
        };
        budget?: {
          budgetId?: string;
          scope?: {
            workspace?: {};
            project?: {
              projectId?: string;
            };
            identity?: {
              identityExternalId?: string;
            };
            apiKey?: {
              apiKeyId?: string;
            };
            provider?: {
              provider?: string;
            };
            model?: {
              modelId?: string;
            };
          };
          match?: {
            cel?: string;
          };
          limits?: {
            period?: string;
            amount?: number;
            tokenLimit?: number;
          };
          rateLimit?: {
            requestsPerMinute?: number;
          };
          isActive?: boolean;
          expiresAt?: Date;
          createdAt?: Date;
          updatedAt?: Date;
          usage?: {
            amount?: number;
            tokens?: number;
            requests?: number;
          };
        };
      };
    }
    ```
  </CodeGroup>
</Expandable>