The Payiano's Request Trace is an invaluable resource for businesses, serving as a
window into the interactions between clients and the API. It offers a detailed account of how the
API is used, including insights into user behaviors, request patterns, and system performance. This
endpoint is instrumental in identifying trends, pinpointing areas for improvement, and ensuring
optimal functionality of the API.
Overall, the Request Trace is a critical tool for maintaining the health and efficiency of the API. It
empowers businesses to make data-driven decisions, improve integration capabilities, and ultimately
contributes significantly to the success and growth of the organization.
By analyzing the data collected through this endpoint, businesses can gain a deeper understanding of
their user base, including how and when the API is accessed most frequently. This information is key
to optimizing the user experience, enhancing system performance, and ensuring the APIs stability and
scalability. Furthermore, the log plays a crucial role in security and compliance, offering the ability
to track and analyze access patterns, detect anomalies, and respond promptly to potential threats or breaches.
Authorization header with access token is required to access this endpoint: Bearer ACCESS-TOKEN
Your access token should be associated to this permission developer.request_traces.view
Request
Request body schema:
application/json
Query parameters:
page
page
Type: integer|null
Default: 1
The page number to be retrieved, for the list of request traces.
So, a combination of page=1 and per_page=25 returns the
first 25 request traces items. A combination of page=2 and
per_page=25 returns the next 25 request traces items.
per_page
per_page
Type: integer|null
Default: 25
Possible values: [1 ... 200]
The maximum number of request traces items to return in the response.
q
q
Type: string|null
Min: 3
This parameter enables free-text search across key request traces fields
(including but not limited to path, host and origin), requiring a minimum of
3 characters per search term. It performs case-insensitive partial
matching, and returns relevance-ranked results while automatically handling
special characters. This provides a simple yet powerful way to quickly find
relevant request traces items. It could accept an array_of_strings as well.
sort
sort
Type: array_of_objects|null
Control the ordering of results with sophisticated multi-column sorting.
Specify an array of objects, each containing a field and direction.
Maximum 5 sort fields per request to maintain
optimal performance.
This attribute specifies the field used for sorting. It can be a direct
attribute of the resource or a related field referenced using dot notation.
direction
required
direction
required
Type: enum
Possible values:
["asc","desc"]
This attribute specifies the sorting direction. It can be either asc
for ascending order or desc for descending order. Please note that
the value is case-sensitive.
filters
filters
Type: object|null
Apply complex filtering conditions using nested logical groups and comparison
operators. Supports advanced querying with and/or logic, multiple
operators, and hierarchical conditions.
The filtering system supports unlimited nesting depth , allowing you to build sophisticated query logic. Each group can contain a mix of conditions and other groups. See Filtering Reference for complete documentation, operator list, and examples.
node
required
node
required
Type: enum
Possible values:
["group"]
Used exclusively as the root filter node.
Specifies the type of the root filter node. At the root level,
only a logical group node is supported. A group node acts as a container that
combines one or more filter conditions or nested groups using AND/OR logic.
Nested group and condition nodes may appear within this root group to build
complex filtering structures.
logic
required
logic
required
Type: enum
Possible values:
["and","or"]
This parameter is used exclusively on group nodes.
Defines how filters within a filter group are logically combined. This
parameter is used exclusively on group nodes and determines how the group
evaluates its child filters or nested groups:
• and — all contained conditions must match
• or — at least one contained condition must match
Logical groups can be nested to construct complex filtering expressions with
mixed AND/OR logic across multiple levels.
filters
required
filters
required
Type: array_of_objects
This parameter is used exclusively on group nodes.
Contains the filter nodes (conditions or groups) within this logical group.
Groups can be nested to create complex hierarchical filtering logic.
node
node
Type: enum
Possible values:
["group","condition"]
Specifies the type of filter node. A filter node can be either a logical
group or a condition:
• group — a logical grouping of multiple filters combined with AND/OR logic
• condition — a single filter condition specifying a field, operator, and value
Filter nodes can be nested to create complex filtering structures.
logic
logic
Type: enum
Possible values:
["and","or"]
This parameter is used exclusively on group nodes.
Defines how filters within a filter group are logically combined. This
parameter is used exclusively on group nodes and determines how the group
evaluates its child filters or nested groups:
• and — all contained conditions must match
• or — at least one contained condition must match
Logical groups can be nested to construct complex filtering expressions with
mixed AND/OR logic across multiple levels.
filters
filters
Type: array_of_objects
This parameter is used exclusively on group nodes.
Contains the filter nodes (conditions or groups) within this logical group.
Groups can be nested to create complex hierarchical filtering logic.
This parameter is used exclusively on condition nodes.
It specifies the field evaluated by the filter condition. The selected
field determines which operators are available and the expected format
of the comparison value based on its data type.
This parameter is used exclusively on condition nodes.
It specifies the comparison operator applied to the selected field. The set of
supported operators depends on the field and its data type, and only operators
that are valid for the chosen field can be used. Available operators for each
field are provided in the response and presented in the filter selection.
Refer to the Filtering Reference for
the complete operator list, expected value formats, and usage examples.
value
value
Type: mixed
This parameter is used exclusively on condition nodes.
The value used by the selected operator to evaluate the field. The expected
structure and data type of this parameter depend on both the field type and
the operator:
• Scalar operators (eq, not_eq, gt, gte, lt, lte,
starts_with, ends_with, contains, and their negations) expect a
single value matching the field type (for example, string or number).
• List operators (in, not_in) expect an array of values compatible
with the field type.
• Range operators (between, not_between) expect an array of exactly
two values representing the inclusive lower and upper bounds.
• Null-check operators (is_null, is_not_null) do not accept a value
and must be used without this parameter.
Supplying a value that does not match the operator or field type will result
in a validation error in strict mode.
See the Filtering Reference for
supported operators, applicable field types, and examples.
Specifies the output format of the datatable response, supporting both
JSON and export file types for easy integration and reporting.
Refer to Response Types for more details.
aggregations
aggregations
Type: object|null
Defines how to aggregate and group data when
response_type is set to json_aggregate. This parameter enables analytical
style responses suitable for dashboards and reports. Refer to Aggregations for more details.
fields
required
fields
required
Type: array_of_objects
Defines the fields to be aggregated along with their respective metrics.
Maximum 5 aggregation fields per
request to maintain optimal performance.
This attribute specifies the name of the field to be aggregated.
metrics
required
metrics
required
Type: array_of_enums
Possible values:
["avg","count","sum"]
Defines the aggregation metrics to apply to the selected field.
Note that the avg and sum metrics are applicable
only to numeric fields.
group_by
required
group_by
required
Type: array_of_objects|null
Specifies the dimensions used to group aggregated
data results. Each object defines a field by which records will be
grouped before applying aggregation metrics. Maximum
5 aggregation group by
fields per request to maintain optimal performance.
Grouping enables developers to analyze data trends across categories, dates,
or other meaningful dimensions.
If no group_by fields are provided, the system performs a global aggregation across the entire dataset. In such cases, the response includes a single summary group, typically referencing the latest created_at value.
field
required
field
required
Type: enum
Possible values:
["created_at","requested_at","updated_at"]
Specifies the field name used for grouping results within the aggregation.
This determines how records are organized and segmented when computing metrics.
When grouping by a datetime or timestamp field such as created_at , the system automatically groups by the date portion only , ignoring the time component. This enables daily-based aggregations instead of precise timestamp level grouping.
By default, grouping operations use the server's timezone ( UTC ). You can override this behavior by specifying the X-Preferred-Response-Timezone header in your request. Learn more about timezone handling in our Datetime & Timezone Reference .
Response
200
Response schema:
application/json
Response body:
total_pages
total_pages
Type: integer
The total number of pages that are available for the Request Traces
search criteria.
current_page
current_page
Type: integer
The current pagination page.
per_page
per_page
Type: integer
The amount of Request Traces items return per page.
total_items
total_items
Type: integer
The total number of Request Traces that match the search criteria.
items
items
Type: array_of_objects
The list of Request Traces that match the search criteria.
id
id
Type: ulid
Length: 26
The unique ID assigned to each Request Trace which is generated
by our system using the ULID format. Each ID is
precisely 26 characters long, ensuring a unique and consistent
identifier for every Request Trace. This ULID is
automatically created by our system and is used to uniquely identify
and track each Request Trace in our database.
path
path
Type: string
The API endpoint that was accessed. This information is vital for
understanding which parts of your API are most used or may need
optimization or additional security measures.
host
host
Type: string
The domain or subdomain used to consume the API. This is essential
for distinguishing between different environments (e.g., production,
sandbox) and services when logging requests.
method
method
Type: string
The HTTP method used in the request, such as GET, POST, PUT,
or DELETE. Knowing the method helps in analyzing the intent and nature
of API interactions — for example, GET is typically used for retrieving
data, while POST is used to create new resources.
origin
origin
Type: string|null
The domain from which the request originated. It's important for
identifying the source of the traffic, understanding user behavior,
and detecting potentially malicious sources.
response_time
response_time
Type: integer
The Milliseconds taken to process the request. Critical for
assessing the performance of your API and identifying slow or
problematic endpoints.
client_agent
client_agent
Type: string|null
Information about the client's software (browser, OS). This helps
in understanding the environments in which your API is used and
ensuring compatibility across different systems.
client_ip
client_ip
Type: string|null
The IP address of the client making the request. Useful for
geo-locating users, analyzing traffic patterns, and detecting
suspicious activities.
request_query
request_query
Type: mixed|null
Query parameters often dictate how the data should be filtered
or customized when returned by the API. For instance, parameters
might specify which fields to return, limit the number of records,
or apply specific filters. It helps in understanding these user
preferences and requirements.
request_body
request_body
Type: mixed|null
The data sent by the client in the request. Essential for debugging
issues, understanding user behavior, and optimizing the user experience.
request_headers
request_headers
Type: mixed|null
Headers sent by the client. These can provide context about the request,
such as authentication tokens, preferred languages, and client capabilities.
response_code
response_code
Type: integer
The HTTP status code returned (e.g., 200 OK, 422 Unprocessable
Entity). Important for monitoring the health of your API and identifying
errors or issues that need attention.
response_body
response_body
Type: mixed|null
The data sent back to the client in response to their request. Crucial
for ensuring the correct operation of your API and understanding how
responses are handled by clients.
response_headers
response_headers
Type: mixed|null
Headers sent back in the response. They can include metadata about the
response, such as content type and cache controls, which are important
for client-side processing and optimization.
requested_at
requested_at
Type: datetime
Date of when the request was made. This is essential for monitoring API
usage over time, identifying peak usage periods, and planning for scaling.
This attribute can be formatted as an ISO 8601
string or a UNIX timestamp in milliseconds,
depending on the preferred datetime format specified in the request header (e.g., 2024-08-04T14:22:01Z or
1722572118554). By default, the format is UNIX
timestamp in milliseconds.
created_at
created_at
Type: datetime
The created datetime of the request trace.
This attribute can be formatted as an ISO 8601
string or a UNIX timestamp in milliseconds,
depending on the preferred datetime format specified in the request header (e.g., 2024-08-04T14:22:01Z or
1722572118554). By default, the format is UNIX
timestamp in milliseconds.
updated_at
updated_at
Type: datetime
The updated datetime of the request trace.
This attribute can be formatted as an ISO 8601
string or a UNIX timestamp in milliseconds,
depending on the preferred datetime format specified in the request header (e.g., 2024-08-04T14:22:01Z or
1722572118554). By default, the format is UNIX
timestamp in milliseconds.
Response sample:
1{2"per_page": 25,3"total_pages": 1,4"total_items": 1,5"current_page": 1,6"items": [7{8"id": "01hqh45s7826hfwdze8dp1z21f",9"path": "v1/client/customers",10"host": "api.payiano.com",11"method": "POST",12"origin": "my.payiano.com",13"response_time": 1,14"client_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36",15"client_ip": "199.36.158.100",16"request_query": {17"includes": [18"customer.billding_address"19]20},21"request_body": {22"name": "Yara Kamal",23"email": "yara@pyngy.com",24"reference_id": "db64355a-8e8d-31e8-a782-2dce8057fe61"25},26"request_headers": {27"host": [28"api.payiano.com"29],30"accept": [31"application/json"32],33"authorization": "Bearer eyJpdiI***********ZRcGQUG4",34"user-agent": [35"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36"36]37},38"response_code": 422,39"response_body": {40"message": "The reference id has already been taken.",41"errors": {42"reference_id": [43"The reference id has already been taken."44]45}46},47"response_headers": {48"Cache-Control": [49"no-cache, private"50],51"Date": [52"Mon, 29 Jan 2024 07:22:21 GMT"53],54"Content-Type": [55"application/json"56]57},58"requested_at": "1722572118554",59"created_at": "1722572118554",60"updated_at": "1722572118554"61}62]63}