# Python SDK Ingest API Reference

Detailed API reference for the Ingest resource in the Pay-i Python SDK

# 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](python-sdk-ingest.md).

# Method Reference

| Method              | Description                           | Return Type      | Access Pattern                 | REST API Endpoint                    |
| ------------------- | ------------------------------------- | ---------------- | ------------------------------ | ------------------------------------ |
| [`units()`](#units) | Submit a single event with usage data | `IngestResponse` | `response.xproxy_result.field` | [REST Ingest API](/docs/rest-ingest) |

> **Note:** For bulk event ingestion options, please contact [support@pay-i.com](mailto:support@pay-i.com).

# Response Types

## IngestResponse

Returned by the `units()` method.

```python
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.

```python
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.

```python
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()

```python
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](/docs/rest-ingest) 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:**

```python
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}%)")
```