Identities SDK Reference - Orq.ai Documentation

Identities

List Identities

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

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)

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();

Show Parameters

{
    "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],
}

{
  limit?: number;
  startingAfter?: string;
  endingBefore?: string;
  search?: string;
  filterByTags?: string[];
  includeMetrics?: boolean;
  sortBy?: string;
  includeBudget?: boolean;
}

Show Response

{
    "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,
}

{
  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;
}

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.

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)

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();

Show Parameters

{
    "external_id": str,  # required
    "display_name": Optional[str],
    "email": Optional[str],
    "avatar_url": Optional[str],
    "tags": List[str],
    "metadata": {},  # optional
}

{
  externalId: string;  // required
  displayName?: string;
  email?: string;
  avatarUrl?: string;
  tags?: string[];
  metadata?: {};
}

Show Response

{
    "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],
            },
        },
    },
}

{
  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;
      };
    };
  };
}

Retrieve an Identity

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

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)

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();

Show Parameters

{
    "id": str,  # required
    "include_metrics": Optional[bool],
    "include_budget": Optional[bool],
}

{
  id: string;  // required
  includeMetrics?: boolean;
  includeBudget?: boolean;
}

Show Response

{
    "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],
            },
        },
    },
}

{
  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;
      };
    };
  };
}

Delete an Identity

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

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)

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();

Show Parameters

{
    "id": str,  # required
}

{
  id: string;  // required
}

Update an Identity

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

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)

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();

Show Parameters

{
    "id": str,  # required
    "display_name": Optional[str],
    "email": Optional[str],
    "avatar_url": Optional[str],
    "tags": List[str],
    "metadata": {},  # optional
}

{
  id: string;  // required
  updateIdentityRequest: {  // required
    displayName?: string;
    email?: string;
    avatarUrl?: string;
    tags?: string[];
    metadata?: {};
  };
}

Show Response

{
    "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],
            },
        },
    },
}

{
  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;
      };
    };
  };
}

​Identities

​List Identities

​Create an Identity

​Retrieve an Identity

​Delete an Identity

​Update an Identity

Identities

List Identities

Create an Identity

Retrieve an Identity

Delete an Identity

Update an Identity