Class: Caller

Last published : Nov 12, 2026
XAPI caller description and rate limiting
Related information
XenServer 8.4 Management API

Fields for class: Caller

Field Type Qualifier Description
auto_registered bool RO/runtime True if this caller was created automatically by the rate limiter rather than by an administrator. Auto-registered callers are subject to the max-auto-registered-callers cap.
client_ip string RO/constructor Client IP matching pattern. Same wildcard semantics as user_agent.
groups string set RO/runtime Groups to which this caller has been assigned
last_access datetime RO/runtime Last time a call was received from this caller
name_description string RW a notes field containing human-readable description
name_label string RW a human-readable name
rate_limit Rate_limit ref RO/runtime Rate limiter attached to this caller, if any. Populated via Rate_limit.add_caller rather than set directly.
user_agent string RO/constructor User agent matching pattern. Empty string is a full wildcard; a trailing '*' makes the field a prefix pattern; otherwise the field is matched exactly.
uuid string RO/runtime Unique identifier/object reference

RPCs associated with class: Caller

RPC name: addgroup

Overview:
Add a caller to a group
Signature:
void add_group (session ref session_ref, Caller ref self, string group)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Caller ref self The caller to update
string group Group the caller is being added to
Minimum Role: pool-operator
Return Type: void

RPC name: create

Overview:
Create a new Caller instance, and return its handle.
Signature:
Caller ref create (session ref session_ref, Caller record args)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Caller record args All constructor arguments
Minimum Role: pool-admin
Return Type: Caller ref
reference to the newly created object

RPC name: destroy

Overview:
Destroy the specified Caller instance.
Signature:
void destroy (session ref session_ref, Caller ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Caller ref self reference to the object
Minimum Role: pool-admin
Return Type: void

RPC name: getall

Overview:
Return a list of all the Callers known to the system.
Signature:
Caller ref set get_all (session ref session_ref)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Minimum Role: read-only
Return Type: Caller ref set
references to all objects

RPC name: getallrecords

Overview:
Return a map of Caller references to Caller records for all Callers known to the system.
Signature:
(Caller ref -> Caller record) map get_all_records (session ref session_ref)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Minimum Role: read-only
Return Type: (Caller ref -> Caller record) map
records of all objects

RPC name: getautoregistered

Overview:
Get the autoregistered field of the given Caller.
Signature:
bool get_auto_registered (session ref session_ref, Caller ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Caller ref self reference to the object
Minimum Role: read-only
Return Type: bool
value of the field

RPC name: getbynamelabel

Overview:
Get all the Caller instances with the given label.
Signature:
Caller ref set get_by_name_label (session ref session_ref, string label)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
string label label of object to return
Minimum Role: read-only
Return Type: Caller ref set
references to objects with matching names

RPC name: getbyuuid

Overview:
Get a reference to the Caller instance with the specified UUID.
Signature:
Caller ref get_by_uuid (session ref session_ref, string uuid)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
string uuid UUID of object to return
Minimum Role: read-only
Return Type: Caller ref
reference to the object

RPC name: getclientip

Overview:
Get the clientip field of the given Caller.
Signature:
string get_client_ip (session ref session_ref, Caller ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Caller ref self reference to the object
Minimum Role: read-only
Return Type: string
value of the field

RPC name: getgroups

Overview:
Get the groups field of the given Caller.
Signature:
string set get_groups (session ref session_ref, Caller ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Caller ref self reference to the object
Minimum Role: read-only
Return Type: string set
value of the field

RPC name: getlastaccess

Overview:
Get the lastaccess field of the given Caller.
Signature:
datetime get_last_access (session ref session_ref, Caller ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Caller ref self reference to the object
Minimum Role: read-only
Return Type: datetime
value of the field

RPC name: getnamedescription

Overview:
Get the name/description field of the given Caller.
Signature:
string get_name_description (session ref session_ref, Caller ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Caller ref self reference to the object
Minimum Role: read-only
Return Type: string
value of the field

RPC name: getnamelabel

Overview:
Get the name/label field of the given Caller.
Signature:
string get_name_label (session ref session_ref, Caller ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Caller ref self reference to the object
Minimum Role: read-only
Return Type: string
value of the field

RPC name: getratelimit

Overview:
Get the ratelimit field of the given Caller.
Signature:
Rate_limit ref get_rate_limit (session ref session_ref, Caller ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Caller ref self reference to the object
Minimum Role: read-only
Return Type: Rate_limit ref
value of the field

RPC name: getrecord

Overview:
Get a record containing the current state of the given Caller.
Signature:
Caller record get_record (session ref session_ref, Caller ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Caller ref self reference to the object
Minimum Role: read-only
Return Type: Caller record
all fields from the object

RPC name: getuseragent

Overview:
Get the useragent field of the given Caller.
Signature:
string get_user_agent (session ref session_ref, Caller ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Caller ref self reference to the object
Minimum Role: read-only
Return Type: string
value of the field

RPC name: getuuid

Overview:
Get the uuid field of the given Caller.
Signature:
string get_uuid (session ref session_ref, Caller ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Caller ref self reference to the object
Minimum Role: read-only
Return Type: string
value of the field

RPC name: queryallusage

Overview:
Return percaller usage for every known caller, sorted by token use descending.
Signature:
string set set query_all_usage (session ref session_ref)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Minimum Role: pool-operator
Return Type: string set set
Rows of uuid; namelabel; tokens; calls, highest tokens first

RPC name: querycallcount

Overview:
Return number of calls made by this caller since Xapi startup
Signature:
int query_call_count (session ref session_ref, Caller ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Caller ref self The caller to query
Minimum Role: pool-operator
Return Type: int
Calls made by the caller since Xapi startup

RPC name: querygroupcallcount

Overview:
Return number of calls made since Xapi startup by the callers in the named group.
Signature:
int query_group_call_count (session ref session_ref, string group)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
string group Caller group to aggregate over
Minimum Role: pool-operator
Return Type: int
Number of calls made by the callers in the group

RPC name: querygrouptokenusage

Overview:
Return tokens used since Xapi startup by the callers in the named group.
Signature:
float query_group_token_usage (session ref session_ref, string group)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
string group Caller group to aggregate over
Minimum Role: pool-operator
Return Type: float
Tokens used by the group since Xapi startup

RPC name: querytokenusage

Overview:
Return tokens used by this caller since Xapi startup
Signature:
float query_token_usage (session ref session_ref, Caller ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Caller ref self The caller to query
Minimum Role: pool-operator
Return Type: float
Tokens used by the caller since Xapi startup

RPC name: removegroup

Overview:
Remove a caller from a group
Signature:
void remove_group (session ref session_ref, Caller ref self, string group)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Caller ref self The caller to update
string group Group the caller is removed from
Minimum Role: pool-operator
Return Type: void

RPC name: setnamedescription

Overview:
Set the name/description field of the given Caller.
Signature:
void set_name_description (session ref session_ref, Caller ref self, string value)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Caller ref self reference to the object
string value New value to set
Minimum Role: pool-admin
Return Type: void

RPC name: setnamelabel

Overview:
Set the name/label field of the given Caller.
Signature:
void set_name_label (session ref session_ref, Caller ref self, string value)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Caller ref self reference to the object
string value New value to set
Minimum Role: pool-admin
Return Type: void