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 @ingest Decorator

When using the @ingest decorator on your functions that make direct provider calls:

The decorator internally receives an xproxy_result from its automatic call to the Ingest API
Important: This result is not currently returned or easily accessible by your application code calling the decorated function
Your function receives only the original provider response
If you need access to real-time cost data when using the @ingest decorator, please contact [email protected] for assistance

Without @ingest Decorator

When making a direct call to a GenAI provider without using the @ingest decorator:

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
See the Manual Event Submission 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

It contains cost and/or limit information about the request and indicates when a limit blocked a request from completing. It has a slightly different structure depending on whether the request succeeded or failed, 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": "26",
  "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 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.
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. Pay-i can also incorporate your charging mechanics and business model to provide revenue and margin calculations alongside the `base` cost. If you need access to this feature, please contact [email protected]. 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