The `xproxy_result` Object

The xproxy_result object contains essential information about a request's execution, including cost calculations and limit status. It is returned whenever a request completes successfully (HTTP 200) and under certain failure conditions, such as when a limit blocks a request (HTTP 400).

Availability by Integration Method

Where and how you can access the xproxy_result object depends on your integration method:

Direct Provider Call with Telemetry (Recommended Approach)

Using @track decorator or track_context() function

When using the @track decorator or track_context() function with direct provider calls:

Both @track and track_context() automatically submit telemetry data to the Ingest API, which returns an xproxy_result object
Important: This xproxy_result data is not currently returned or easily accessible in your application code
Your function or code block receives only the original provider response
If you need access to real-time cost data when using these annotations, please contact [email protected] for assistance

Without @track decorator or track_context() function

When making a direct call to a GenAI provider without using the @track decorator or track_context() function:

You will need to manually call the Ingest API to submit telemetry data
The Ingest API call will return the xproxy_result object containing cost calculations and limit status
For Python applications, see the Python SDK Ingest API documentation for details on response handling
For other languages, see the REST Ingest API documentation for details on the response format

Proxy Routing (For Blocking Limits)

When using Pay-i as a proxy router between your application and the GenAI provider (advanced approach used specifically for enforcing blocking limits):

Synchronous Requests: The xproxy_result object appears as a separate JSON object alongside the normal provider response
Streaming Requests: The xproxy_result object is provided in the last streamed chunk in a top level property of the chunk object

It contains cost and/or limit information about the request and indicates when a limit blocked a request from completing. Successful requests will include cost information, while failed requests do not include these fields because failed requests have no cost.

Example Successful Request (200)

"xproxy_result": {
  "request_id": "40000616-0000-7000-b63f-84710c7967bb",
  "request_tags": ["all", "used", "tags", "are", "returned", "for", "confirmation"],
  "resource_id": "3f5d48cf-7a61-42bc-b369-626599b74e74",
  "use_case_id": "2f9e1c5a-7b3d-48f6-a0d9-6e4f2c8b1a3e",
  "limits": {
    "cde4836a-9d2e-4179-5146-08dc8c8ba991": {
    	"state": "exceeded"
    },
    "a21163d1-b123-4652-5147-08dc8c8ba991": {
    	"state": "ok"
    },
    "70a8b4f6-3e1d-4c9a-b8f2-9d5e6c7a8d3b": {
      "state": "exceeded"
    },
  },
  "cost": {
    "currency": "USD",
    "input": {
    	"base": "0.00028"
    },
    "output": {
    	"base": "0.01962"
    },
    "total": {
    	"base": "0.0199"
    }
  }
}

xproxy_result Fields

Field	Description
request_id	An identifier that can later be used to reference this specific request for debugging.
request_tags	All Request Tags that were passed in as part of the request are returned to enable programmatic confirmation/testing.
resource_id	An identifier that references the specific Resource used in the request. This is returned as an opaque ID and not a name (e.g. 'gpt-4o') because resources are versioned, and the version used will differ based on the timestamp of the request. See Resource Versions for more information.
use_case_id	The `use_case_id` used for the request. See Use Cases (Continued) for more information. When Pay-i generates a new `use_case_id`, this field contains the generated value.
limits	A dictionary containing all `limit-id`s that were passed in as part of the request, and their Limit States after the request was completed.
cost	The breakdown of how much this request costs across input and output units. The cost of the call, as charged by the Provider is called the `base` cost. When a request has failed, usually due to being blocked by a limit, there is no cost and therefore this field is not returned.
blocked_limit_ids	If a request is blocked by one or more limits, then this array contains the list of `limit-id`s responsible for blocking the call. See the Example Unsuccessful Request section for more information. This array is only present if the call was blocked by one or more limits.

The xproxy_result Object