Overview

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

Method Reference

Method	Description	Return Type	Access Pattern	REST API Endpoint
`create()`	Creates a new spending limit	`LimitResponse`	`response.limit.field`	Create a limit
`retrieve()`	Gets a specific limit's details and status	`LimitResponse`	`response.limit.field`	Get a limit
`list()`	Lists all defined limits	`SyncCursorPage[LimitListResponse]`	`response.items[index].field`	Get limits
`update()`	Updates an existing limit	`LimitResponse`	`response.limit.field`	Update a limit
`delete()`	Deletes a specific limit	`DefaultResponse`	`response.request_id`	Delete a limit
`reset()`	Resets a limit's current value to zero	`LimitHistoryResponse`	`response.limit_history.field`	Reset a limit

Response Types

The limits API returns several different response types depending on the method called:

LimitResponse

Returned by create(), retrieve(), and update() methods.

LimitResponse:
    limit: Limit                          # Nested Limit object with all details
    request_id: str                       # Server-generated trace identifier for the HTTP request
    message: Optional[str]                # Optional status message

Limit:
    limit_id: str                         # Unique identifier
    limit_name: str                       # Name of the limit
    limit_type: Literal["block", "allow"] # How the limit behaves
    max: float                            # Maximum limit value
    totals: TotalCostData                 # Current usage data
    limit_tags: Optional[List[str]]       # Associated tags
    threshold: Optional[float]            # Notification threshold

LimitListResponse

Returned by the list() method as items in a SyncCursorPage.

SyncCursorPage[LimitListResponse]:
    # Iterable collection with pagination handling
    data: List[LimitListResponse]         # The actual limit data
    has_next_page(): bool                 # Whether more pages exist
    next_page(): SyncCursorPage           # Get next page of results

LimitListResponse:
    # Unlike LimitResponse, fields are directly accessible
    # (not nested under a "limit" property)
    limit_id: str                         # Unique identifier
    limit_name: str                       # Name of the limit
    limit_type: Literal["block", "allow"] # How the limit behaves
    max: float                            # Maximum limit value
    totals: TotalCostData                 # Current usage data
    limit_tags: Optional[List[str]]       # Associated tags
    threshold: Optional[float]            # Notification threshold

DefaultResponse

Returned by the delete() method.

DefaultResponse:
    request_id: str                       # Server-generated trace identifier for the HTTP request
    message: Optional[str]                # Optional status message

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.

LimitHistoryResponse

Returned by the reset() method.

LimitHistoryResponse:
    limit_history: LimitHistory           # Nested LimitHistory object
    request_id: str                       # Server-generated trace identifier for the HTTP request
    message: Optional[str]                # Optional status message

LimitHistory:
    # All fields are optional in this type
    limit_id: Optional[str]                          # Unique identifier
    limit_name: Optional[str]                        # Name of the limit
    limit_type: Optional[Literal["block", "allow"]]  # How the limit behaves
    max: Optional[float]                             # Maximum limit value
    totals: Optional[TotalCostData]                  # Current usage data
    limit_tags: Optional[List[str]]                  # Associated tags
    limit_reset_timestamp: Optional[datetime]        # When the reset occurred

Method Details

Method	Description	Return Type	Access Pattern	REST API Endpoint
`create()`	Creates a new spending limit	`LimitResponse`	`response.limit.field`	Create a limit
`retrieve()`	Gets a specific limit's details and status	`LimitResponse`	`response.limit.field`	Get a limit
`list()`	Lists all defined limits	`SyncCursorPage[LimitListResponse]`	`response.items[index].field`	Get limits
`update()`	Updates an existing limit	`LimitResponse`	`response.limit.field`	Update a limit
`delete()`	Deletes a specific limit	`DefaultResponse`	`response.request_id`	Delete a limit
`reset()`	Resets a limit's current value to zero	`LimitHistoryResponse`	`response.limit_history.field`	Reset a limit

create()

client.limits.create(
    limit_name: str,
    max: float,
    limit_type: Optional[Literal["block", "allow"]] = None,
    limit_tags: Optional[List[str]] = None,
    threshold: Optional[float] = None,  # Value between 0.75 and 0.99 (75% to 99%)
    billing_model_id: Optional[str] = None,
    limit_basis: Optional[Literal["base", "billed"]] = None
) -> LimitResponse

Creates a new spending limit with the specified parameters. This operation is idempotent only when all parameters exactly match - creating a limit with the same name and identical parameters will return the existing limit ID. However, if any parameter differs (even optional ones), the operation will fail with an error that the limit name already exists.

Calls: Create a limit REST API endpoint

Parameters:

limit_name (required): The name of the limit
max (required): The maximum value for the limit
limit_type: Whether the limit blocks or allows requests when reached
limit_tags: Tags to associate with the limit
threshold: Optional notification threshold (value between 0.75 and 0.99, representing 75% to 99% of the limit)

Note: There are additional internal parameters (billing_model_id and limit_basis) that may appear in the SDK code but are not intended for public usage.

Returns: A LimitResponse object containing the created limit details and ID. See Response Types for details on the structure.

Example:

response = client.limits.create(
    limit_name="Monthly Budget",
    max=100.0,
    limit_type="block"
)
limit_id = response.limit.limit_id

retrieve()

client.limits.retrieve(
    limit_id: str
) -> LimitResponse

Retrieves the current status and details of a specific limit by ID.

Calls: Get a limit REST API endpoint

Parameters:

limit_id (required): The ID of the limit to retrieve

Returns: A LimitResponse object containing the limit's details, current usage, and status. See Response Types for details on the structure.

Example:

# Using a stored limit ID
limit_response = client.limits.retrieve(limit_id="lim_1234567890")
limit = limit_response.limit
current_usage = limit.totals.cost.total.base
max_limit = limit.max
usage_ratio = current_usage / max_limit
print(f"Type: {limit.limit_type}, Threshold: {limit.threshold * 100:.0f}%")
print(f"Current usage: ${current_usage:.5f} of ${max_limit:.2f}")
print(f"Usage ratio: {usage_ratio:.5f}")

list()

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

Retrieves all your configured spending limits, with optional filtering by name.

Calls: Get limits REST API endpoint

Parameters:

cursor: Pagination cursor for fetching next page of results
limit: Maximum number of items per page (page size)
limit_name: Filter results by a specific limit name
sort_ascending: Sort order (true for ascending, false for descending)

Returns: A list-like object containing all your spending limits

Example: Listing all limits

# Get all your spending limits
limits = client.limits.list()

# Iterate through all limits (SDK handles pagination automatically)
for limit in limits:
    current_usage = limit.totals.cost.total.base
    max_limit = limit.max
    print(f"Limit: {limit.limit_name}")
    print(f"  Type: {limit.limit_type}, Threshold: {limit.threshold * 100:.0f}%")
    print(f"  Max: ${max_limit:.2f}, Current: ${current_usage:.5f}")

Example: Finding a specific limit by name

# When you know the exact name, you can access the first item directly
limit_results = client.limits.list(limit_name="Monthly Budget")
if limit_results.items:
    limit = limit_results.items[0]  # Direct access to first (and likely only) item
    print(f"Found limit: {limit.limit_name} (ID: {limit.limit_id})")
    print(f"Current usage: ${limit.totals.cost.total.base:.5f} of ${limit.max:.2f}")

update()

client.limits.update(
    limit_id: str,
    limit_name: Optional[str] = None,
    max: Optional[float] = None
) -> LimitResponse

Updates an existing limit with new values. Only the limit_name and max properties can be modified after a limit is created.

Calls: Update a limit REST API endpoint

Parameters:

limit_id (required): The ID of the limit to update
limit_name: New name for the limit
max: New maximum value for the limit

Immutable Properties: These properties cannot be changed after limit creation:

limit_type: The limit behavior (block vs allow)
threshold: The notification threshold percentage

Note: If you need to change immutable properties, you must create a new limit with the desired configuration and delete the old one.

Returns: A LimitResponse object containing the updated limit details

Example:

# Using a stored limit ID
updated_limit = client.limits.update(
    limit_id="lim_1234567890",
    max=200.0  # Double the budget
)

delete()

client.limits.delete(
    limit_id: str
) -> DefaultResponse

Deletes a specific limit.

Calls: Delete a limit REST API endpoint

Parameters:

limit_id (required): The ID of the limit to delete

Returns: A DefaultResponse object confirming deletion

Example:

# Using a stored limit ID
result = client.limits.delete(limit_id="lim_1234567890")

reset()

client.limits.reset(
    limit_id: str,
    reset_date: Optional[Union[str, datetime]] = None
) -> LimitHistoryResponse

Resets the current value of a limit back to zero.

Calls: Reset a limit REST API endpoint

Parameters:

limit_id (required): The ID of the limit to reset
reset_date (optional): Effective date for the reset (defaults to current time if not provided)

Returns: A LimitHistoryResponse object with the reset limit history

Example:

# Using a stored limit ID
reset_result = client.limits.reset(limit_id="lim_1234567890")
reset_limit_history = reset_result.limit_history
print(f"Limit '{reset_limit_history.limit_name}' has been reset")

# To get the current usage, we need to retrieve the limit again
updated_limit = client.limits.retrieve(limit_id="lim_1234567890").limit
new_usage = updated_limit.totals.cost.total.base
print(f"Current value after reset: ${new_usage:.5f}")  # Should be 0