> For the complete documentation index, see [llms.txt](https://developer.emporix.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.emporix.io/api-references/readme/api-reference/agent-logs.md).

# Agent Logs

Read Agent Logs

## Listing agent requests

> Retrieves agent requests based on the provided query.\
> \
> Supports offset pagination (\`pageNumber\`, \`pageSize\`) and cursor pagination (\`next\`, \`prev\`). Cursor pagination is active when \`next\` or \`prev\` is provided.\
> \
> In cursor mode:\
> \- \`next\` and \`prev\` cannot be used together and return \`400\`.\
> \- \`pageNumber\` is ignored.\
> \- the \`X-Total-Count\` request header is ignored and the \`X-Total-Count\` response header is not returned.\
> \
> If no sort is provided, results are returned in \`\_id:ASC\` order. If a sort is provided, \`\_id:ASC\` is appended as a tie-breaker when \`\_id\` is not already part of the sort.

```json
{"openapi":"3.0.0","info":{"title":"AI Service","version":"0.0.1"},"tags":[{"name":"Agent Logs","description":"Read Agent Logs"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["ai.agent_read"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"scopes":{"ai.text_manage":"Needed to execute actions related to the text generation.","ai.completion_manage":"Needed to execute actions related to the AI completions.","ai.agentexecution_manage":"Needed to execute agentic chat.","ai.agentexecution_manage_own":"Needed to execute agentic chat by customers.","ai.agent_read":"Needed to read AI agents.","ai.agent_manage":"Needed to manage AI agents."},"tokenUrl":"https://api.emporix.io/oauth/token"}}}},"responses":{"200_resp_GET_agent_requests":{"description":"List of agent requests.","headers":{"X-Total-Count":{"description":"Total number of agent requests for the given criteria. Returned only for offset pagination when requested with the `X-Total-Count` header.","schema":{"type":"integer","format":"int32"}},"X-Next-Cursor":{"description":"Opaque cursor for retrieving the next page. Returned on non-empty responses when a next page exists.","schema":{"type":"string"}},"X-Prev-Cursor":{"description":"Opaque cursor for retrieving the previous page. Returned on non-empty responses when a previous page exists.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AgentRequestResponse"}}}}},"400_resp_common":{"description":"The request was syntactically incorrect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"401_resp_common":{"description":"The authorization token is invalid or has expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessageFault"}}}},"403_resp_common":{"description":"Authorization scopes of the access token are not sufficient and do not match the scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}},"schemas":{"AgentRequestResponse":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the request log."},"sessionId":{"type":"string","description":"Unique identifier of the session."},"requestId":{"type":"string","description":"Unique identifier of the request."},"triggerAgentId":{"type":"string","description":"Unique identifier of the agent that triggered the request."},"collaborationAgents":{"type":"array","items":{"type":"string"},"description":"List of agent IDs that collaborated in this request."},"severity":{"$ref":"#/components/schemas/LogSeverity"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/AgentLogMessageResponse"},"description":"List of log messages associated with this request."},"duration":{"type":"integer","format":"int64","description":"Duration of the request in seconds."},"promptTokens":{"type":"integer","format":"int64","description":"Cumulative LLM prompt token count for this request."},"completionTokens":{"type":"integer","format":"int64","description":"Cumulative LLM completion token count for this request."},"agentVersion":{"type":"integer","minimum":1,"description":"Version of the agent which triggered the request."},"metadata":{"$ref":"#/components/schemas/MetadataResponse"}}},"LogSeverity":{"type":"string","enum":["INFO","WARNING","ERROR"],"description":"Severity level of the log entry."},"AgentLogMessageResponse":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time","description":"Timestamp when the log message was created."},"severity":{"$ref":"#/components/schemas/LogSeverity"},"message":{"type":"string","description":"The log message content."},"agentId":{"type":"string","description":"Unique identifier of the agent that generated the log."},"agentVersion":{"type":"integer","minimum":1,"description":"Version of the agent that wrote this log message."},"requestId":{"type":"string","description":"Unique identifier of the request associated with the log."},"isBusinessLog":{"type":"boolean","description":"Whether this is a business log entry."}}},"MetadataResponse":{"allOf":[{"$ref":"#/components/schemas/MetadataRequest"},{"type":"object","properties":{"createdAt":{"description":"Date and time when the object was created. The value is approved as an ISO-8601 representation of an Instant. For example: `2022-04-30T13:18:02.379Z`","type":"string"},"modifiedAt":{"description":"Date and time when the object was last modified. The value is approved as an ISO-8601 representation of an Instant. For example: `2022-04-30T13:18:02.379Z`","type":"string"}},"required":["version","createdAt","modifiedAt"]}]},"MetadataRequest":{"type":"object","properties":{"version":{"minimum":1,"type":"integer","description":"Version of the object. The version is required during the update operation because of the optimistic locking mechanism."}},"required":["version"]},"ErrorMessage":{"type":"object","properties":{"code":{"type":"integer"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"},"details":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"}}}}},"description":""},"ErrorMessageFault":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}},"paths":{"/ai-service/{tenant}/agentic/logs/requests":{"get":{"summary":"Listing agent requests","operationId":"GET-ai-list-requests","responses":{"200":{"$ref":"#/components/responses/200_resp_GET_agent_requests"},"400":{"$ref":"#/components/responses/400_resp_common"},"401":{"$ref":"#/components/responses/401_resp_common"},"403":{"$ref":"#/components/responses/403_resp_common"}},"description":"Retrieves agent requests based on the provided query.\n\nSupports offset pagination (`pageNumber`, `pageSize`) and cursor pagination (`next`, `prev`). Cursor pagination is active when `next` or `prev` is provided.\n\nIn cursor mode:\n- `next` and `prev` cannot be used together and return `400`.\n- `pageNumber` is ignored.\n- the `X-Total-Count` request header is ignored and the `X-Total-Count` response header is not returned.\n\nIf no sort is provided, results are returned in `_id:ASC` order. If a sort is provided, `_id:ASC` is appended as a tie-breaker when `_id` is not already part of the sort.","tags":["Agent Logs"]}}}}
```

## Retrieving agent request by ID

> Retrieves the agent request by given ID.

```json
{"openapi":"3.0.0","info":{"title":"AI Service","version":"0.0.1"},"tags":[{"name":"Agent Logs","description":"Read Agent Logs"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["ai.agent_read"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"scopes":{"ai.text_manage":"Needed to execute actions related to the text generation.","ai.completion_manage":"Needed to execute actions related to the AI completions.","ai.agentexecution_manage":"Needed to execute agentic chat.","ai.agentexecution_manage_own":"Needed to execute agentic chat by customers.","ai.agent_read":"Needed to read AI agents.","ai.agent_manage":"Needed to manage AI agents."},"tokenUrl":"https://api.emporix.io/oauth/token"}}}},"parameters":{"fields":{"schema":{"type":"string"},"in":"query","name":"fields","description":"Fields to be returned in the response."}},"responses":{"200_resp_GET_agent_request":{"description":"A single agent request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRequestResponse"}}}},"401_resp_common":{"description":"The authorization token is invalid or has expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessageFault"}}}},"403_resp_common":{"description":"Authorization scopes of the access token are not sufficient and do not match the scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"404_resp_common":{"description":"Example response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}},"schemas":{"AgentRequestResponse":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the request log."},"sessionId":{"type":"string","description":"Unique identifier of the session."},"requestId":{"type":"string","description":"Unique identifier of the request."},"triggerAgentId":{"type":"string","description":"Unique identifier of the agent that triggered the request."},"collaborationAgents":{"type":"array","items":{"type":"string"},"description":"List of agent IDs that collaborated in this request."},"severity":{"$ref":"#/components/schemas/LogSeverity"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/AgentLogMessageResponse"},"description":"List of log messages associated with this request."},"duration":{"type":"integer","format":"int64","description":"Duration of the request in seconds."},"promptTokens":{"type":"integer","format":"int64","description":"Cumulative LLM prompt token count for this request."},"completionTokens":{"type":"integer","format":"int64","description":"Cumulative LLM completion token count for this request."},"agentVersion":{"type":"integer","minimum":1,"description":"Version of the agent which triggered the request."},"metadata":{"$ref":"#/components/schemas/MetadataResponse"}}},"LogSeverity":{"type":"string","enum":["INFO","WARNING","ERROR"],"description":"Severity level of the log entry."},"AgentLogMessageResponse":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time","description":"Timestamp when the log message was created."},"severity":{"$ref":"#/components/schemas/LogSeverity"},"message":{"type":"string","description":"The log message content."},"agentId":{"type":"string","description":"Unique identifier of the agent that generated the log."},"agentVersion":{"type":"integer","minimum":1,"description":"Version of the agent that wrote this log message."},"requestId":{"type":"string","description":"Unique identifier of the request associated with the log."},"isBusinessLog":{"type":"boolean","description":"Whether this is a business log entry."}}},"MetadataResponse":{"allOf":[{"$ref":"#/components/schemas/MetadataRequest"},{"type":"object","properties":{"createdAt":{"description":"Date and time when the object was created. The value is approved as an ISO-8601 representation of an Instant. For example: `2022-04-30T13:18:02.379Z`","type":"string"},"modifiedAt":{"description":"Date and time when the object was last modified. The value is approved as an ISO-8601 representation of an Instant. For example: `2022-04-30T13:18:02.379Z`","type":"string"}},"required":["version","createdAt","modifiedAt"]}]},"MetadataRequest":{"type":"object","properties":{"version":{"minimum":1,"type":"integer","description":"Version of the object. The version is required during the update operation because of the optimistic locking mechanism."}},"required":["version"]},"ErrorMessageFault":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}},"ErrorMessage":{"type":"object","properties":{"code":{"type":"integer"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"},"details":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"}}}}},"description":""}}},"paths":{"/ai-service/{tenant}/agentic/logs/requests/{requestId}":{"get":{"parameters":[{"$ref":"#/components/parameters/fields"}],"summary":"Retrieving agent request by ID","operationId":"GET-ai-retrieve-request","responses":{"200":{"$ref":"#/components/responses/200_resp_GET_agent_request"},"401":{"$ref":"#/components/responses/401_resp_common"},"403":{"$ref":"#/components/responses/403_resp_common"},"404":{"$ref":"#/components/responses/404_resp_common"}},"description":"Retrieves the agent request by given ID.","tags":["Agent Logs"]}}}}
```

## Searching agent requests

> Searches for agent requests based on the provided query.\
> \
> Supports offset pagination (\`pageNumber\`, \`pageSize\`) and cursor pagination (\`next\`, \`prev\`). Cursor pagination is active when \`next\` or \`prev\` is provided.\
> \
> In cursor mode:\
> \- \`next\` and \`prev\` cannot be used together and return \`400\`.\
> \- \`pageNumber\` is ignored.\
> \- the \`X-Total-Count\` request header is ignored and the \`X-Total-Count\` response header is not returned.\
> \
> If no sort is provided, results are returned in \`\_id:ASC\` order. If a sort is provided, \`\_id:ASC\` is appended as a tie-breaker when \`\_id\` is not already part of the sort.

```json
{"openapi":"3.0.0","info":{"title":"AI Service","version":"0.0.1"},"tags":[{"name":"Agent Logs","description":"Read Agent Logs"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["ai.agent_read"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"scopes":{"ai.text_manage":"Needed to execute actions related to the text generation.","ai.completion_manage":"Needed to execute actions related to the AI completions.","ai.agentexecution_manage":"Needed to execute agentic chat.","ai.agentexecution_manage_own":"Needed to execute agentic chat by customers.","ai.agent_read":"Needed to read AI agents.","ai.agent_manage":"Needed to manage AI agents."},"tokenUrl":"https://api.emporix.io/oauth/token"}}}},"parameters":{"pageSize":{"schema":{"type":"string"},"in":"query","name":"pageSize","description":"The number of documents to be retrieved per page."},"pageNumber":{"schema":{"type":"string"},"in":"query","name":"pageNumber","description":"The page number to be retrieved. The size of the pages should be specified by the `pageSize` parameter."},"trait_cursor_next":{"name":"next","in":"query","required":false,"schema":{"type":"string","maxLength":4096},"description":"Opaque cursor from the `X-Next-Cursor` response header. Use it to retrieve the next set of results.\nCannot be combined with `prev` in the same request; sending both returns `400 Bad Request`.\nWhen provided, cursor pagination is active: `pageNumber` is ignored and the `X-Total-Count` request header is ignored (the `X-Total-Count` response header is not returned).\n"},"trait_cursor_prev":{"name":"prev","in":"query","required":false,"schema":{"type":"string","maxLength":4096},"description":"Opaque cursor from the `X-Prev-Cursor` response header. Use it to retrieve the previous set of results. Cannot be combined with `next` in the same request; sending both returns `400 Bad Request`. When provided, cursor pagination is active and `pageNumber` is ignored.\n"},"sort":{"schema":{"type":"string"},"in":"query","name":"sort","description":"List of properties used to sort the results, separated by colons."},"fields":{"schema":{"type":"string"},"in":"query","name":"fields","description":"Fields to be returned in the response."},"header_xTotalCount":{"schema":{"type":"boolean"},"in":"header","name":"X-Total-Count","description":"Flag indicating whether the total number of retrieved results should be returned."}},"responses":{"200_resp_GET_agent_requests":{"description":"List of agent requests.","headers":{"X-Total-Count":{"description":"Total number of agent requests for the given criteria. Returned only for offset pagination when requested with the `X-Total-Count` header.","schema":{"type":"integer","format":"int32"}},"X-Next-Cursor":{"description":"Opaque cursor for retrieving the next page. Returned on non-empty responses when a next page exists.","schema":{"type":"string"}},"X-Prev-Cursor":{"description":"Opaque cursor for retrieving the previous page. Returned on non-empty responses when a previous page exists.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AgentRequestResponse"}}}}},"400_resp_common":{"description":"The request was syntactically incorrect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"401_resp_common":{"description":"The authorization token is invalid or has expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessageFault"}}}},"403_resp_common":{"description":"Authorization scopes of the access token are not sufficient and do not match the scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}},"schemas":{"AgentRequestResponse":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the request log."},"sessionId":{"type":"string","description":"Unique identifier of the session."},"requestId":{"type":"string","description":"Unique identifier of the request."},"triggerAgentId":{"type":"string","description":"Unique identifier of the agent that triggered the request."},"collaborationAgents":{"type":"array","items":{"type":"string"},"description":"List of agent IDs that collaborated in this request."},"severity":{"$ref":"#/components/schemas/LogSeverity"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/AgentLogMessageResponse"},"description":"List of log messages associated with this request."},"duration":{"type":"integer","format":"int64","description":"Duration of the request in seconds."},"promptTokens":{"type":"integer","format":"int64","description":"Cumulative LLM prompt token count for this request."},"completionTokens":{"type":"integer","format":"int64","description":"Cumulative LLM completion token count for this request."},"agentVersion":{"type":"integer","minimum":1,"description":"Version of the agent which triggered the request."},"metadata":{"$ref":"#/components/schemas/MetadataResponse"}}},"LogSeverity":{"type":"string","enum":["INFO","WARNING","ERROR"],"description":"Severity level of the log entry."},"AgentLogMessageResponse":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time","description":"Timestamp when the log message was created."},"severity":{"$ref":"#/components/schemas/LogSeverity"},"message":{"type":"string","description":"The log message content."},"agentId":{"type":"string","description":"Unique identifier of the agent that generated the log."},"agentVersion":{"type":"integer","minimum":1,"description":"Version of the agent that wrote this log message."},"requestId":{"type":"string","description":"Unique identifier of the request associated with the log."},"isBusinessLog":{"type":"boolean","description":"Whether this is a business log entry."}}},"MetadataResponse":{"allOf":[{"$ref":"#/components/schemas/MetadataRequest"},{"type":"object","properties":{"createdAt":{"description":"Date and time when the object was created. The value is approved as an ISO-8601 representation of an Instant. For example: `2022-04-30T13:18:02.379Z`","type":"string"},"modifiedAt":{"description":"Date and time when the object was last modified. The value is approved as an ISO-8601 representation of an Instant. For example: `2022-04-30T13:18:02.379Z`","type":"string"}},"required":["version","createdAt","modifiedAt"]}]},"MetadataRequest":{"type":"object","properties":{"version":{"minimum":1,"type":"integer","description":"Version of the object. The version is required during the update operation because of the optimistic locking mechanism."}},"required":["version"]},"ErrorMessage":{"type":"object","properties":{"code":{"type":"integer"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"},"details":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"}}}}},"description":""},"ErrorMessageFault":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}},"QParamSearchBody":{"type":"object","properties":{"q":{"type":"string","description":"A standard query parameter is used to search for specific values. \n\nSee: [Standard Practices - Query parameter](https://developer.emporix.io/api-documentation/standard-practices/q-param)\n"}}}},"requestBodies":{"QParamSearchBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QParamSearchBody"}}}}}},"paths":{"/ai-service/{tenant}/agentic/logs/requests/search":{"post":{"parameters":[{"$ref":"#/components/parameters/pageSize"},{"$ref":"#/components/parameters/pageNumber"},{"$ref":"#/components/parameters/trait_cursor_next"},{"$ref":"#/components/parameters/trait_cursor_prev"},{"$ref":"#/components/parameters/sort"},{"$ref":"#/components/parameters/fields"},{"$ref":"#/components/parameters/header_xTotalCount"}],"summary":"Searching agent requests","operationId":"POST-ai-search-requests","responses":{"200":{"$ref":"#/components/responses/200_resp_GET_agent_requests"},"400":{"$ref":"#/components/responses/400_resp_common"},"401":{"$ref":"#/components/responses/401_resp_common"},"403":{"$ref":"#/components/responses/403_resp_common"}},"requestBody":{"$ref":"#/components/requestBodies/QParamSearchBody"},"description":"Searches for agent requests based on the provided query.\n\nSupports offset pagination (`pageNumber`, `pageSize`) and cursor pagination (`next`, `prev`). Cursor pagination is active when `next` or `prev` is provided.\n\nIn cursor mode:\n- `next` and `prev` cannot be used together and return `400`.\n- `pageNumber` is ignored.\n- the `X-Total-Count` request header is ignored and the `X-Total-Count` response header is not returned.\n\nIf no sort is provided, results are returned in `_id:ASC` order. If a sort is provided, `_id:ASC` is appended as a tie-breaker when `_id` is not already part of the sort.","tags":["Agent Logs"]}}}}
```

## Listing agent sessions

> Retrieves agent sessions based on the provided query.\
> \
> Supports offset pagination (\`pageNumber\`, \`pageSize\`) and cursor pagination (\`next\`, \`prev\`). Cursor pagination is active when \`next\` or \`prev\` is provided.\
> \
> In cursor mode:\
> \- \`next\` and \`prev\` cannot be used together and return \`400\`.\
> \- \`pageNumber\` is ignored.\
> \- the \`X-Total-Count\` request header is ignored and the \`X-Total-Count\` response header is not returned.\
> \
> If no sort is provided, results are returned in \`\_id:ASC\` order. If a sort is provided, \`\_id:ASC\` is appended as a tie-breaker when \`\_id\` is not already part of the sort.

```json
{"openapi":"3.0.0","info":{"title":"AI Service","version":"0.0.1"},"tags":[{"name":"Agent Logs","description":"Read Agent Logs"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["ai.agent_read"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"scopes":{"ai.text_manage":"Needed to execute actions related to the text generation.","ai.completion_manage":"Needed to execute actions related to the AI completions.","ai.agentexecution_manage":"Needed to execute agentic chat.","ai.agentexecution_manage_own":"Needed to execute agentic chat by customers.","ai.agent_read":"Needed to read AI agents.","ai.agent_manage":"Needed to manage AI agents."},"tokenUrl":"https://api.emporix.io/oauth/token"}}}},"responses":{"200_resp_GET_agent_sessions":{"description":"List of agent sessions.","headers":{"X-Total-Count":{"description":"Total number of agent sessions for the given criteria. Returned only for offset pagination when requested with the `X-Total-Count` header.","schema":{"type":"integer","format":"int32"}},"X-Next-Cursor":{"description":"Opaque cursor for retrieving the next page. Returned on non-empty responses when a next page exists.","schema":{"type":"string"}},"X-Prev-Cursor":{"description":"Opaque cursor for retrieving the previous page. Returned on non-empty responses when a previous page exists.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AgentSessionResponse"}}}}},"400_resp_common":{"description":"The request was syntactically incorrect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"401_resp_common":{"description":"The authorization token is invalid or has expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessageFault"}}}},"403_resp_common":{"description":"Authorization scopes of the access token are not sufficient and do not match the scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}},"schemas":{"AgentSessionResponse":{"type":"object","properties":{"sessionId":{"type":"string","description":"Unique identifier of the session."},"triggerAgentId":{"type":"string","description":"Unique identifier of the agent that triggered the session."},"severity":{"$ref":"#/components/schemas/LogSeverity"},"agents":{"type":"array","items":{"type":"string"},"description":"List of agent IDs that participated in this session."},"messages":{"type":"array","items":{"$ref":"#/components/schemas/AgentLogMessageResponse"},"description":"List of log messages associated with this session."},"duration":{"type":"integer","format":"int64","description":"Duration of the session in seconds."},"promptTokens":{"type":"integer","format":"int64","description":"Cumulative LLM prompt token count for this session."},"completionTokens":{"type":"integer","format":"int64","description":"Cumulative LLM completion token count for this session."},"metadata":{"$ref":"#/components/schemas/MetadataResponse"}}},"LogSeverity":{"type":"string","enum":["INFO","WARNING","ERROR"],"description":"Severity level of the log entry."},"AgentLogMessageResponse":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time","description":"Timestamp when the log message was created."},"severity":{"$ref":"#/components/schemas/LogSeverity"},"message":{"type":"string","description":"The log message content."},"agentId":{"type":"string","description":"Unique identifier of the agent that generated the log."},"agentVersion":{"type":"integer","minimum":1,"description":"Version of the agent that wrote this log message."},"requestId":{"type":"string","description":"Unique identifier of the request associated with the log."},"isBusinessLog":{"type":"boolean","description":"Whether this is a business log entry."}}},"MetadataResponse":{"allOf":[{"$ref":"#/components/schemas/MetadataRequest"},{"type":"object","properties":{"createdAt":{"description":"Date and time when the object was created. The value is approved as an ISO-8601 representation of an Instant. For example: `2022-04-30T13:18:02.379Z`","type":"string"},"modifiedAt":{"description":"Date and time when the object was last modified. The value is approved as an ISO-8601 representation of an Instant. For example: `2022-04-30T13:18:02.379Z`","type":"string"}},"required":["version","createdAt","modifiedAt"]}]},"MetadataRequest":{"type":"object","properties":{"version":{"minimum":1,"type":"integer","description":"Version of the object. The version is required during the update operation because of the optimistic locking mechanism."}},"required":["version"]},"ErrorMessage":{"type":"object","properties":{"code":{"type":"integer"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"},"details":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"}}}}},"description":""},"ErrorMessageFault":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}},"paths":{"/ai-service/{tenant}/agentic/logs/sessions":{"get":{"summary":"Listing agent sessions","operationId":"GET-ai-list-sessions","responses":{"200":{"$ref":"#/components/responses/200_resp_GET_agent_sessions"},"400":{"$ref":"#/components/responses/400_resp_common"},"401":{"$ref":"#/components/responses/401_resp_common"},"403":{"$ref":"#/components/responses/403_resp_common"}},"description":"Retrieves agent sessions based on the provided query.\n\nSupports offset pagination (`pageNumber`, `pageSize`) and cursor pagination (`next`, `prev`). Cursor pagination is active when `next` or `prev` is provided.\n\nIn cursor mode:\n- `next` and `prev` cannot be used together and return `400`.\n- `pageNumber` is ignored.\n- the `X-Total-Count` request header is ignored and the `X-Total-Count` response header is not returned.\n\nIf no sort is provided, results are returned in `_id:ASC` order. If a sort is provided, `_id:ASC` is appended as a tie-breaker when `_id` is not already part of the sort.","tags":["Agent Logs"]}}}}
```

## Retrieving agent session by ID

> Retrieves the agent session by given ID.

```json
{"openapi":"3.0.0","info":{"title":"AI Service","version":"0.0.1"},"tags":[{"name":"Agent Logs","description":"Read Agent Logs"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["ai.agent_read"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"scopes":{"ai.text_manage":"Needed to execute actions related to the text generation.","ai.completion_manage":"Needed to execute actions related to the AI completions.","ai.agentexecution_manage":"Needed to execute agentic chat.","ai.agentexecution_manage_own":"Needed to execute agentic chat by customers.","ai.agent_read":"Needed to read AI agents.","ai.agent_manage":"Needed to manage AI agents."},"tokenUrl":"https://api.emporix.io/oauth/token"}}}},"parameters":{"fields":{"schema":{"type":"string"},"in":"query","name":"fields","description":"Fields to be returned in the response."}},"responses":{"200_resp_GET_agent_session":{"description":"A single agent session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentSessionResponse"}}}},"401_resp_common":{"description":"The authorization token is invalid or has expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessageFault"}}}},"403_resp_common":{"description":"Authorization scopes of the access token are not sufficient and do not match the scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"404_resp_common":{"description":"Example response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}},"schemas":{"AgentSessionResponse":{"type":"object","properties":{"sessionId":{"type":"string","description":"Unique identifier of the session."},"triggerAgentId":{"type":"string","description":"Unique identifier of the agent that triggered the session."},"severity":{"$ref":"#/components/schemas/LogSeverity"},"agents":{"type":"array","items":{"type":"string"},"description":"List of agent IDs that participated in this session."},"messages":{"type":"array","items":{"$ref":"#/components/schemas/AgentLogMessageResponse"},"description":"List of log messages associated with this session."},"duration":{"type":"integer","format":"int64","description":"Duration of the session in seconds."},"promptTokens":{"type":"integer","format":"int64","description":"Cumulative LLM prompt token count for this session."},"completionTokens":{"type":"integer","format":"int64","description":"Cumulative LLM completion token count for this session."},"metadata":{"$ref":"#/components/schemas/MetadataResponse"}}},"LogSeverity":{"type":"string","enum":["INFO","WARNING","ERROR"],"description":"Severity level of the log entry."},"AgentLogMessageResponse":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time","description":"Timestamp when the log message was created."},"severity":{"$ref":"#/components/schemas/LogSeverity"},"message":{"type":"string","description":"The log message content."},"agentId":{"type":"string","description":"Unique identifier of the agent that generated the log."},"agentVersion":{"type":"integer","minimum":1,"description":"Version of the agent that wrote this log message."},"requestId":{"type":"string","description":"Unique identifier of the request associated with the log."},"isBusinessLog":{"type":"boolean","description":"Whether this is a business log entry."}}},"MetadataResponse":{"allOf":[{"$ref":"#/components/schemas/MetadataRequest"},{"type":"object","properties":{"createdAt":{"description":"Date and time when the object was created. The value is approved as an ISO-8601 representation of an Instant. For example: `2022-04-30T13:18:02.379Z`","type":"string"},"modifiedAt":{"description":"Date and time when the object was last modified. The value is approved as an ISO-8601 representation of an Instant. For example: `2022-04-30T13:18:02.379Z`","type":"string"}},"required":["version","createdAt","modifiedAt"]}]},"MetadataRequest":{"type":"object","properties":{"version":{"minimum":1,"type":"integer","description":"Version of the object. The version is required during the update operation because of the optimistic locking mechanism."}},"required":["version"]},"ErrorMessageFault":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}},"ErrorMessage":{"type":"object","properties":{"code":{"type":"integer"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"},"details":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"}}}}},"description":""}}},"paths":{"/ai-service/{tenant}/agentic/logs/sessions/{sessionId}":{"get":{"parameters":[{"$ref":"#/components/parameters/fields"}],"summary":"Retrieving agent session by ID","operationId":"GET-ai-retrieve-session","responses":{"200":{"$ref":"#/components/responses/200_resp_GET_agent_session"},"401":{"$ref":"#/components/responses/401_resp_common"},"403":{"$ref":"#/components/responses/403_resp_common"},"404":{"$ref":"#/components/responses/404_resp_common"}},"description":"Retrieves the agent session by given ID.","tags":["Agent Logs"]}}}}
```

## Searching agent sessions

> Searches for agent sessions based on the provided query.\
> \
> Supports offset pagination (\`pageNumber\`, \`pageSize\`) and cursor pagination (\`next\`, \`prev\`). Cursor pagination is active when \`next\` or \`prev\` is provided.\
> \
> In cursor mode:\
> \- \`next\` and \`prev\` cannot be used together and return \`400\`.\
> \- \`pageNumber\` is ignored.\
> \- the \`X-Total-Count\` request header is ignored and the \`X-Total-Count\` response header is not returned.\
> \
> If no sort is provided, results are returned in \`\_id:ASC\` order. If a sort is provided, \`\_id:ASC\` is appended as a tie-breaker when \`\_id\` is not already part of the sort.

```json
{"openapi":"3.0.0","info":{"title":"AI Service","version":"0.0.1"},"tags":[{"name":"Agent Logs","description":"Read Agent Logs"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["ai.agent_read"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"scopes":{"ai.text_manage":"Needed to execute actions related to the text generation.","ai.completion_manage":"Needed to execute actions related to the AI completions.","ai.agentexecution_manage":"Needed to execute agentic chat.","ai.agentexecution_manage_own":"Needed to execute agentic chat by customers.","ai.agent_read":"Needed to read AI agents.","ai.agent_manage":"Needed to manage AI agents."},"tokenUrl":"https://api.emporix.io/oauth/token"}}}},"parameters":{"pageSize":{"schema":{"type":"string"},"in":"query","name":"pageSize","description":"The number of documents to be retrieved per page."},"pageNumber":{"schema":{"type":"string"},"in":"query","name":"pageNumber","description":"The page number to be retrieved. The size of the pages should be specified by the `pageSize` parameter."},"trait_cursor_next":{"name":"next","in":"query","required":false,"schema":{"type":"string","maxLength":4096},"description":"Opaque cursor from the `X-Next-Cursor` response header. Use it to retrieve the next set of results.\nCannot be combined with `prev` in the same request; sending both returns `400 Bad Request`.\nWhen provided, cursor pagination is active: `pageNumber` is ignored and the `X-Total-Count` request header is ignored (the `X-Total-Count` response header is not returned).\n"},"trait_cursor_prev":{"name":"prev","in":"query","required":false,"schema":{"type":"string","maxLength":4096},"description":"Opaque cursor from the `X-Prev-Cursor` response header. Use it to retrieve the previous set of results. Cannot be combined with `next` in the same request; sending both returns `400 Bad Request`. When provided, cursor pagination is active and `pageNumber` is ignored.\n"},"sort":{"schema":{"type":"string"},"in":"query","name":"sort","description":"List of properties used to sort the results, separated by colons."},"fields":{"schema":{"type":"string"},"in":"query","name":"fields","description":"Fields to be returned in the response."},"header_xTotalCount":{"schema":{"type":"boolean"},"in":"header","name":"X-Total-Count","description":"Flag indicating whether the total number of retrieved results should be returned."}},"responses":{"200_resp_GET_agent_sessions":{"description":"List of agent sessions.","headers":{"X-Total-Count":{"description":"Total number of agent sessions for the given criteria. Returned only for offset pagination when requested with the `X-Total-Count` header.","schema":{"type":"integer","format":"int32"}},"X-Next-Cursor":{"description":"Opaque cursor for retrieving the next page. Returned on non-empty responses when a next page exists.","schema":{"type":"string"}},"X-Prev-Cursor":{"description":"Opaque cursor for retrieving the previous page. Returned on non-empty responses when a previous page exists.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AgentSessionResponse"}}}}},"400_resp_common":{"description":"The request was syntactically incorrect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"401_resp_common":{"description":"The authorization token is invalid or has expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessageFault"}}}},"403_resp_common":{"description":"Authorization scopes of the access token are not sufficient and do not match the scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}},"schemas":{"AgentSessionResponse":{"type":"object","properties":{"sessionId":{"type":"string","description":"Unique identifier of the session."},"triggerAgentId":{"type":"string","description":"Unique identifier of the agent that triggered the session."},"severity":{"$ref":"#/components/schemas/LogSeverity"},"agents":{"type":"array","items":{"type":"string"},"description":"List of agent IDs that participated in this session."},"messages":{"type":"array","items":{"$ref":"#/components/schemas/AgentLogMessageResponse"},"description":"List of log messages associated with this session."},"duration":{"type":"integer","format":"int64","description":"Duration of the session in seconds."},"promptTokens":{"type":"integer","format":"int64","description":"Cumulative LLM prompt token count for this session."},"completionTokens":{"type":"integer","format":"int64","description":"Cumulative LLM completion token count for this session."},"metadata":{"$ref":"#/components/schemas/MetadataResponse"}}},"LogSeverity":{"type":"string","enum":["INFO","WARNING","ERROR"],"description":"Severity level of the log entry."},"AgentLogMessageResponse":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time","description":"Timestamp when the log message was created."},"severity":{"$ref":"#/components/schemas/LogSeverity"},"message":{"type":"string","description":"The log message content."},"agentId":{"type":"string","description":"Unique identifier of the agent that generated the log."},"agentVersion":{"type":"integer","minimum":1,"description":"Version of the agent that wrote this log message."},"requestId":{"type":"string","description":"Unique identifier of the request associated with the log."},"isBusinessLog":{"type":"boolean","description":"Whether this is a business log entry."}}},"MetadataResponse":{"allOf":[{"$ref":"#/components/schemas/MetadataRequest"},{"type":"object","properties":{"createdAt":{"description":"Date and time when the object was created. The value is approved as an ISO-8601 representation of an Instant. For example: `2022-04-30T13:18:02.379Z`","type":"string"},"modifiedAt":{"description":"Date and time when the object was last modified. The value is approved as an ISO-8601 representation of an Instant. For example: `2022-04-30T13:18:02.379Z`","type":"string"}},"required":["version","createdAt","modifiedAt"]}]},"MetadataRequest":{"type":"object","properties":{"version":{"minimum":1,"type":"integer","description":"Version of the object. The version is required during the update operation because of the optimistic locking mechanism."}},"required":["version"]},"ErrorMessage":{"type":"object","properties":{"code":{"type":"integer"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"},"details":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"type":{"type":"string"},"message":{"type":"string"},"moreInfo":{"type":"string"}}}}},"description":""},"ErrorMessageFault":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}},"QParamSearchBody":{"type":"object","properties":{"q":{"type":"string","description":"A standard query parameter is used to search for specific values. \n\nSee: [Standard Practices - Query parameter](https://developer.emporix.io/api-documentation/standard-practices/q-param)\n"}}}},"requestBodies":{"QParamSearchBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QParamSearchBody"}}}}}},"paths":{"/ai-service/{tenant}/agentic/logs/sessions/search":{"post":{"parameters":[{"$ref":"#/components/parameters/pageSize"},{"$ref":"#/components/parameters/pageNumber"},{"$ref":"#/components/parameters/trait_cursor_next"},{"$ref":"#/components/parameters/trait_cursor_prev"},{"$ref":"#/components/parameters/sort"},{"$ref":"#/components/parameters/fields"},{"$ref":"#/components/parameters/header_xTotalCount"}],"summary":"Searching agent sessions","operationId":"POST-ai-search-sessions","responses":{"200":{"$ref":"#/components/responses/200_resp_GET_agent_sessions"},"400":{"$ref":"#/components/responses/400_resp_common"},"401":{"$ref":"#/components/responses/401_resp_common"},"403":{"$ref":"#/components/responses/403_resp_common"}},"requestBody":{"$ref":"#/components/requestBodies/QParamSearchBody"},"description":"Searches for agent sessions based on the provided query.\n\nSupports offset pagination (`pageNumber`, `pageSize`) and cursor pagination (`next`, `prev`). Cursor pagination is active when `next` or `prev` is provided.\n\nIn cursor mode:\n- `next` and `prev` cannot be used together and return `400`.\n- `pageNumber` is ignored.\n- the `X-Total-Count` request header is ignored and the `X-Total-Count` response header is not returned.\n\nIf no sort is provided, results are returned in `_id:ASC` order. If a sort is provided, `_id:ASC` is appended as a tie-breaker when `_id` is not already part of the sort.","tags":["Agent Logs"]}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developer.emporix.io/api-references/readme/api-reference/agent-logs.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.