Overview

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

Method Reference

Method	Description	Return Type	Access Pattern	REST API Endpoint
`units()`	Submit a single event with usage data	`IngestResponse`	`response.xproxy_result.field`	REST Ingest API

Note: For bulk event ingestion options, please contact [email protected].

Response Types

IngestResponse

Returned by the units() method.

IngestResponse:
    request_id: str                        # Server-generated trace identifier
    message: Optional[str]                 # Optional status message
    event_timestamp: Optional[datetime]    # When the event occurred
    ingest_timestamp: Optional[datetime]   # When Pay-i processed the event
    xproxy_result: Optional[XProxyResult]  # Detailed result information

XProxyResult

Contains detailed information about cost, limit status, and other metadata.

XProxyResult:
    request_id: str                                    # Server-generated trace identifier
    cost: float                                        # Total cost for the request
    limit_blocks: Optional[Dict[str, LimitStatus]]     # Status of limits that blocked the request
    limit_statuses: Optional[Dict[str, LimitStatus]]   # Status of all relevant limits
    experience_instance_id: Optional[str]              # Associated experience instance ID
    use_case_instance_id: Optional[str]                # Associated use case instance ID
    properties: Optional[Dict[str, Any]]               # Additional metadata or custom properties

LimitStatus

Contains information about a limit's status.

LimitStatus:
    limit_id: str                              # Unique identifier for the limit
    limit_name: str                            # Name of the limit
    limit_type: Literal["block", "allow"]      # Whether the limit blocks or allows when reached
    max: float                                 # Maximum value for the limit
    current: float                             # Current value of the limit
    available: float                           # Remaining capacity (max - current)
    percent_used: float                        # Percentage of limit used (current/max)
    threshold_hit: Optional[bool]              # Whether a notification threshold was reached
    limit_hit: Optional[bool]                  # Whether the limit was reached
    reset_timestamp: Optional[datetime]        # When the limit will reset

Method Details

units()

client.ingest.units(
    category: str,
    resource: Optional[str] = None,
    input_tokens: Optional[int] = None,
    output_tokens: Optional[int] = None,
    total_tokens: Optional[int] = None,
    user_id: Optional[str] = None,
    experience_instance_id: Optional[str] = None,
    use_case_instance_id: Optional[str] = None,
    latency_ms: Optional[int] = None,
    properties: Optional[dict] = None,
    request_id: Optional[str] = None,
    idempotency_key: Optional[str] = None,
    provider_request_id: Optional[str] = None,
    provider_request_json: Optional[str] = None,
    provider_response_json: Optional[str] = None,
    timestamp: Optional[datetime] = None
) -> IngestResponse

Submits a single event with usage data to Pay-i.

Calls: REST Ingest API REST API endpoint

Parameters:

category (required): The category the resource belongs to (e.g., "system.openai")
resource: Specific resource being used (e.g., "gpt-4")
input_tokens: Number of input tokens used
output_tokens: Number of output tokens generated
total_tokens: Total tokens (if input/output breakdown is not available)
user_id: ID for user-level attribution and tracking
experience_instance_id: Associates the event with an experience instance
use_case_instance_id: Associates the event with a use case instance
latency_ms: End-to-end latency in milliseconds
properties: Additional metadata or custom properties
request_id: Custom unique identifier for the request
idempotency_key: Key to prevent duplicate submissions
provider_request_id: Original provider's request ID
provider_request_json: JSON string of the provider request
provider_response_json: JSON string of the provider response
timestamp: Event timestamp (defaults to current time)

Returns: An IngestResponse object containing:

request_id: Server-generated trace identifier
message: Optional status message
event_timestamp: When the event occurred
ingest_timestamp: When Pay-i processed the event
xproxy_result: Detailed information including cost, limits status, and request metadata

Example:

response = client.ingest.units(
    category="system.openai",
    resource="gpt-4",
    input_tokens=150,
    output_tokens=350,
    user_id="user-123",
    properties={
        "request_type": "chat",
        "context": "customer_support"
    }
)

# Access cost information
print(f"Request cost: ${response.xproxy_result.cost}")

# Check limit status
if response.xproxy_result.limit_blocks:
    print("Request was blocked by the following limits:")
    for limit_id, status in response.xproxy_result.limit_blocks.items():
        print(f"- {status.limit_name}: {status.current}/{status.max} ({status.percent_used}%)")