Overview

This document provides detailed reference information for the client.categories resource in the Pay-i Python SDK. For usage examples and best practices, see the Python SDK Categories and Resources Guide.

Method Reference

Response Types

The categories and resources API returns several different response types depending on the method called:

CategoryResponse

Returned in SyncCursorPage by the categories.list() method.

CategoryResponse:
    category: str                        # The name of the category
    category_type: str                   # Type of category (e.g., "system", "custom")
    category_description: Optional[str]  # Optional description of the category

CategoryDeleteResponse

Returned by the categories.delete() method.

CategoryDeleteResponse:
    request_id: str                      # Server-generated trace identifier 
    message: Optional[str]               # Optional status message

CategoryDeleteResourceResponse

Returned by the categories.delete_resource() method.

CategoryDeleteResourceResponse:
    request_id: str                      # Server-generated trace identifier 
    message: Optional[str]               # Optional status message

CategoryResourceResponse

Returned by the categories.resources.create(), categories.resources.retrieve(), categories.resources.delete() methods and in SyncCursorPage by the categories.list_resources() and categories.resources.list() methods.

CategoryResourceResponse:
    resource_id: str                     # Unique identifier for the resource version
    category: str                        # The category this resource belongs to
    resource: str                        # The name of the resource
    units: Dict[str, Units]              # Dictionary of unit types and pricing
    max_input_units: Optional[int]       # Maximum input units allowed
    max_output_units: Optional[int]      # Maximum output units allowed
    max_total_units: Optional[int]       # Maximum total units allowed
    creation_timestamp: Optional[str]    # When the resource was created
    start_timestamp: Optional[str]       # When the resource becomes available
    resource_scope: Optional[str]        # Scope of the resource (e.g., "global", "datazone")
    aliases: Optional[List[str]]         # Alternative names for this resource
    
Units:
    input_price: float                   # Price per input unit
    output_price: float                  # Price per output unit

The request_id is the HTTP request's trace identifier that uniquely identifies the request across the Pay-i system. This is a standard field present in all Pay-i API responses as they inherit from a common ResponseBase class. The trace ID can be used for correlating requests in logs, troubleshooting issues, and tracking request flow through the system.

Method Details

categories.list()

client.categories.list(
    cursor: Optional[str] = None,
    limit: Optional[int] = None,
    sort_ascending: Optional[bool] = None
) -> SyncCursorPage[CategoryResponse]

Retrieves a list of all categories.

Calls: Get Categories REST API endpoint

Parameters:

• cursor: Pagination cursor for fetching next page of results
• limit: Maximum number of items per page (page size)
• sort_ascending: Sort order (true for ascending, false for descending)

Returns: A paginated response containing CategoryResponse objects

Example:

# List all categories
categories = client.categories.list()
for category in categories:
    print(f"Category: {category.category}")

categories.delete()

client.categories.delete(
    category: str
) -> CategoryDeleteResponse

Deletes a specific category and all its resources.

Calls: Delete Category Resources REST API endpoint

Parameters:

• category (required): The name of the category to delete

Returns: A CategoryDeleteResponse object confirming deletion

Example:

# Delete a custom category
result = client.categories.delete(category="custom.my_category")
print(f"Category deleted with request ID: {result.request_id}")

categories.delete_resource()

client.categories.delete_resource(
    resource: str,
    category: str
) -> CategoryDeleteResourceResponse

Deletes all versions of a specific resource from a category.

Calls: Delete Category Resource REST API endpoint

Parameters:

• resource (required): The name of the resource to delete
• category (required): The category containing the resource

Returns: A CategoryDeleteResourceResponse object confirming deletion

Example:

# Delete a resource from a category
result = client.categories.delete_resource(
    category="custom.my_category",
    resource="my_custom_model"
)
print(f"Resource deleted with request ID: {result.request_id}")

categories.list_resources()

client.categories.list_resources(
    category: str,
    cursor: Optional[str] = None,
    limit: Optional[int] = None,
    sort_ascending: Optional[bool] = None
) -> SyncCursorPage[CategoryResourceResponse]

Retrieves a list of all resources for a specific category.

Calls: Get Resources List REST API endpoint

Parameters:

• category (required): The category to list resources for
• cursor: Pagination cursor for fetching next page of results
• limit: Maximum number of items per page (page size)
• sort_ascending: Sort order (true for ascending, false for descending)

Returns: A paginated response containing CategoryResourceResponse objects

Example:

# List all resources in the OpenAI category
resources = client.categories.list_resources(category="system.openai")
for resource in resources:
    print(f"Resource: {resource.resource}")

categories.resources.create()

client.categories.resources.create(
    resource: str,
    category: str,
    units: Dict[str, Units],
    max_input_units: Optional[int] = None,
    max_output_units: Optional[int] = None,
    max_total_units: Optional[int] = None,
    start_timestamp: Optional[Union[str, datetime]] = None
) -> CategoryResourceResponse

Creates a new resource in a specified category.

Calls: Create Resource REST API endpoint

Parameters:

• resource (required): The name of the resource to create
• category (required): The category to create the resource in
• units (required): Dictionary defining the pricing units for input and output
• max_input_units: Maximum input units allowed
• max_output_units: Maximum output units allowed
• max_total_units: Maximum total units allowed
• start_timestamp: When the resource becomes available

Returns: A CategoryResourceResponse object containing the created resource details

Example:

from datetime import datetime, timezone

# Create a custom resource
response = client.categories.resources.create(
    resource="my_custom_model",
    category="custom.my_category",
    units={
        "text": {
            "input_price": 0.000015,
            "output_price": 0.000075
        }
    },
    max_input_units=16000,
    max_output_units=4000,
    start_timestamp=datetime.now(timezone.utc)
)
print(f"Created resource with ID: {response.resource_id}")

categories.resources.retrieve()

client.categories.resources.retrieve(
    resource_id: str,
    category: str,
    resource: str
) -> CategoryResourceResponse

Retrieves details of a specific resource version.

Calls: Get Resource REST API endpoint

Parameters:

• resource_id (required): The ID of the specific resource version
• category (required): The category containing the resource
• resource (required): The name of the resource

Returns: A CategoryResourceResponse object with resource details

Example:

# Retrieve a specific resource version
resource = client.categories.resources.retrieve(
    resource_id="resource123abc",
    category="system.openai",
    resource="gpt-4o"
)
print(f"Resource: {resource.resource}")
print(f"Input price: ${resource.units['text'].input_price}")
print(f"Output price: ${resource.units['text'].output_price}")

categories.resources.list()

client.categories.resources.list(
    resource: str,
    category: str,
    cursor: Optional[str] = None,
    limit: Optional[int] = None,
    sort_ascending: Optional[bool] = None
) -> SyncCursorPage[CategoryResourceResponse]

Lists all versions of a specific resource.

Calls: Get Resources REST API endpoint

Parameters:

• resource (required): The name of the resource
• category (required): The category containing the resource
• cursor: Pagination cursor for fetching next page of results
• limit: Maximum number of items per page (page size)
• sort_ascending: Sort order (true for ascending, false for descending)

Returns: A paginated response containing CategoryResourceResponse objects

Example:

# List all versions of a resource
versions = client.categories.resources.list(
    resource="gpt-4",
    category="system.openai"
)
for version in versions:
    print(f"Version ID: {version.resource_id}, Created: {version.creation_timestamp}")

categories.resources.delete()

client.categories.resources.delete(
    resource_id: str,
    category: str,
    resource: str
) -> CategoryResourceResponse

Deletes a specific version of a resource.

Calls: Delete Resource REST API endpoint

Parameters:

• resource_id (required): The ID of the specific resource version to delete
• category (required): The category containing the resource
• resource (required): The name of the resource

Returns: A CategoryResourceResponse object confirming deletion

Example:

# Delete a specific resource version
result = client.categories.resources.delete(
    resource_id="resource456def",
    category="custom.my_category",
    resource="my_custom_model"
)
print(f"Deleted resource version: {result.resource_id}")

System Categories

Pay-i supports the following system categories:

Custom Categories and Resources

In addition to the system categories, Pay-i supports custom categories and resources. These are created and managed through the API.

Creating a Custom Category

Custom categories are automatically created when you create a resource in a category that doesn't exist yet. Custom category names should start with a descriptive prefix.

# This will automatically create the custom.my_models category
response = client.categories.resources.create(
    resource="my_fine_tuned_model",
    category="custom.my_models",
    units={
        "text": {
            "input_price": 0.00002,
            "output_price": 0.00008
        }
    },
    max_input_units=50000
)

Resource Scope

For Azure OpenAI models, various deployment configurations can affect pricing. The system supports different resource scopes:

Managing Resource Lifecycle

As your AI infrastructure evolves, you may need to update or remove resources that are no longer needed. When you delete a resource using the API methods described above, Pay-i performs a "soft delete" operation. This means:

1. The resource will no longer appear in list operations
2. You cannot create new events using that resource
3. Historical data using that resource remains valid and accessible
4. Cost calculations and analytics for previously ingested events continue to function normally

This approach ensures your historical data integrity is maintained while allowing you to manage your current resource catalog effectively.

Resource Naming and Versioning

For detailed information about resource naming patterns, versioning, and how Pay-i resolves model aliases, please refer to the Model Versions and Time-Based Resolution section in the Managed Categories and Resources documentation.