Agent Logs

Read Agent Logs

Listing agent requests

get

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.

Required scopes

This endpoint requires the following scopes:

• : Needed to read AI agents.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstringRequired

Your Emporix tenant name.

Note: The tenant name should always be provided in lowercase.

Query parameters

qstringOptional

A standard query parameter is used to search for specific values.

See: Standard Practices - Query parameter

pageSizestringOptional

The number of documents to be retrieved per page.

pageNumberstringOptional

The page number to be retrieved. The size of the pages should be specified by the pageSize parameter.

nextstring · max: 4096Optional

Opaque cursor from the X-Next-Cursor response header. Use it to retrieve the next set of results. Cannot be combined with prev in the same request; sending both returns 400 Bad Request. When 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).

prevstring · max: 4096Optional

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.

sortstringOptional

List of properties used to sort the results, separated by colons.

fieldsstringOptional

Fields to be returned in the response.

Header parameters

X-Total-CountbooleanOptional

Flag indicating whether the total number of retrieved results should be returned.

Responses

200

List of agent requests.

application/json

400

The request was syntactically incorrect.

application/json

401

The authorization token is invalid or has expired.

application/json

403

Authorization scopes of the access token are not sufficient and do not match the scopes required by the endpoint.

application/json

get/ai-service/{tenant}/agentic/logs/requests

GET /ai-service/{tenant}/agentic/logs/requests HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

[
  {
    "id": "req-123e4567-e89b-12d3-a456-426614174000",
    "sessionId": "sess-123e4567-e89b-12d3-a456-426614174000",
    "requestId": "req-123e4567-e89b-12d3-a456-426614174000",
    "triggerAgentId": "complaint-agent",
    "collaborationAgents": [
      "complaint-agent-categorization"
    ],
    "severity": "INFO",
    "messages": [
      {
        "timestamp": "2025-01-15T10:30:27.167Z",
        "severity": "INFO",
        "message": "Agent started processing request",
        "agentId": "complaint-agent",
        "agentVersion": 3,
        "requestId": "req-123e4567-e89b-12d3-a456-426614174000",
        "isBusinessLog": false
      },
      {
        "timestamp": "2025-01-15T10:30:28.234Z",
        "severity": "INFO",
        "message": "Retrieved order details successfully",
        "agentId": "complaint-agent",
        "agentVersion": 3,
        "requestId": "req-123e4567-e89b-12d3-a456-426614174000",
        "isBusinessLog": true
      }
    ],
    "duration": 45,
    "promptTokens": 1234,
    "completionTokens": 567,
    "agentVersion": 3,
    "metadata": {
      "version": 1,
      "createdAt": "2025-01-15T10:30:27.167Z",
      "modifiedAt": "2025-01-15T10:30:28.234Z"
    }
  }
]

Retrieving agent request by ID

get

Retrieves the agent request by given ID.

Required scopes

This endpoint requires the following scopes:

• : Needed to read AI agents.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstringRequired

Your Emporix tenant name.

Note: The tenant name should always be provided in lowercase.

requestIdstringRequired

Query parameters

fieldsstringOptional

Fields to be returned in the response.

Responses

200

A single agent request.

application/json

idstringOptional

Unique identifier of the request log.

sessionIdstringOptional

Unique identifier of the session.

requestIdstringOptional

Unique identifier of the request.

triggerAgentIdstringOptional

Unique identifier of the agent that triggered the request.

collaborationAgentsstring[]Optional

List of agent IDs that collaborated in this request.

severitystring · enumOptional

Severity level of the log entry.

Possible values:

durationinteger · int64Optional

Duration of the request in seconds.

promptTokensinteger · int64Optional

Cumulative LLM prompt token count for this request.

completionTokensinteger · int64Optional

Cumulative LLM completion token count for this request.

agentVersioninteger · min: 1Optional

Version of the agent which triggered the request.

401

The authorization token is invalid or has expired.

application/json

403

Authorization scopes of the access token are not sufficient and do not match the scopes required by the endpoint.

application/json

404

Example response

application/json

get/ai-service/{tenant}/agentic/logs/requests/{requestId}

GET /ai-service/{tenant}/agentic/logs/requests/{requestId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "id": "req-123e4567-e89b-12d3-a456-426614174000",
  "sessionId": "sess-123e4567-e89b-12d3-a456-426614174000",
  "requestId": "req-123e4567-e89b-12d3-a456-426614174000",
  "triggerAgentId": "complaint-agent",
  "collaborationAgents": [
    "complaint-agent-categorization"
  ],
  "severity": "INFO",
  "messages": [
    {
      "timestamp": "2025-01-15T10:30:28.234Z",
      "severity": "INFO",
      "message": "Retrieved order details successfully",
      "agentId": "complaint-agent",
      "agentVersion": 3,
      "requestId": "req-123e4567-e89b-12d3-a456-426614174000",
      "isBusinessLog": true
    },
    {
      "timestamp": "2025-01-15T10:30:29.456Z",
      "severity": "WARNING",
      "message": "Order status check returned unexpected value",
      "agentId": "complaint-agent",
      "agentVersion": 3,
      "requestId": "req-123e4567-e89b-12d3-a456-426614174000",
      "isBusinessLog": false
    }
  ],
  "duration": 45,
  "promptTokens": 1234,
  "completionTokens": 567,
  "agentVersion": 3,
  "metadata": {
    "version": 1,
    "createdAt": "2025-01-15T10:30:27.167Z",
    "modifiedAt": "2025-01-15T10:30:29.456Z"
  }
}

Searching agent requests

post

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.

Required scopes

This endpoint requires the following scopes:

• : Needed to read AI agents.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstringRequired

Your Emporix tenant name.

Note: The tenant name should always be provided in lowercase.

Query parameters

pageSizestringOptional

The number of documents to be retrieved per page.

pageNumberstringOptional

The page number to be retrieved. The size of the pages should be specified by the pageSize parameter.

nextstring · max: 4096Optional

Opaque cursor from the X-Next-Cursor response header. Use it to retrieve the next set of results. Cannot be combined with prev in the same request; sending both returns 400 Bad Request. When 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).

prevstring · max: 4096Optional

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.

sortstringOptional

List of properties used to sort the results, separated by colons.

fieldsstringOptional

Fields to be returned in the response.

Header parameters

X-Total-CountbooleanOptional

Flag indicating whether the total number of retrieved results should be returned.

Body

qstringOptional

A standard query parameter is used to search for specific values.

See: Standard Practices - Query parameter

Responses

200

List of agent requests.

application/json

400

The request was syntactically incorrect.

application/json

401

The authorization token is invalid or has expired.

application/json

403

Authorization scopes of the access token are not sufficient and do not match the scopes required by the endpoint.

application/json

post/ai-service/{tenant}/agentic/logs/requests/search

POST /ai-service/{tenant}/agentic/logs/requests/search HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 23

{
  "q": "name:~Complaint"
}

[
  {
    "id": "req-123e4567-e89b-12d3-a456-426614174000",
    "sessionId": "sess-123e4567-e89b-12d3-a456-426614174000",
    "requestId": "req-123e4567-e89b-12d3-a456-426614174000",
    "triggerAgentId": "complaint-agent",
    "collaborationAgents": [
      "complaint-agent-categorization"
    ],
    "severity": "INFO",
    "messages": [
      {
        "timestamp": "2025-01-15T10:30:27.167Z",
        "severity": "INFO",
        "message": "Agent started processing request",
        "agentId": "complaint-agent",
        "agentVersion": 3,
        "requestId": "req-123e4567-e89b-12d3-a456-426614174000",
        "isBusinessLog": false
      },
      {
        "timestamp": "2025-01-15T10:30:28.234Z",
        "severity": "INFO",
        "message": "Retrieved order details successfully",
        "agentId": "complaint-agent",
        "agentVersion": 3,
        "requestId": "req-123e4567-e89b-12d3-a456-426614174000",
        "isBusinessLog": true
      }
    ],
    "duration": 45,
    "promptTokens": 1234,
    "completionTokens": 567,
    "agentVersion": 3,
    "metadata": {
      "version": 1,
      "createdAt": "2025-01-15T10:30:27.167Z",
      "modifiedAt": "2025-01-15T10:30:28.234Z"
    }
  }
]

Listing agent sessions

get

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.

Required scopes

This endpoint requires the following scopes:

• : Needed to read AI agents.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstringRequired

Your Emporix tenant name.

Note: The tenant name should always be provided in lowercase.

Query parameters

qstringOptional

A standard query parameter is used to search for specific values.

See: Standard Practices - Query parameter

pageSizestringOptional

The number of documents to be retrieved per page.

pageNumberstringOptional

The page number to be retrieved. The size of the pages should be specified by the pageSize parameter.

nextstring · max: 4096Optional

Opaque cursor from the X-Next-Cursor response header. Use it to retrieve the next set of results. Cannot be combined with prev in the same request; sending both returns 400 Bad Request. When 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).

prevstring · max: 4096Optional

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.

sortstringOptional

List of properties used to sort the results, separated by colons.

fieldsstringOptional

Fields to be returned in the response.

Header parameters

X-Total-CountbooleanOptional

Flag indicating whether the total number of retrieved results should be returned.

Responses

200

List of agent sessions.

application/json

400

The request was syntactically incorrect.

application/json

401

The authorization token is invalid or has expired.

application/json

403

Authorization scopes of the access token are not sufficient and do not match the scopes required by the endpoint.

application/json

get/ai-service/{tenant}/agentic/logs/sessions

GET /ai-service/{tenant}/agentic/logs/sessions HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

[
  {
    "sessionId": "sess-123e4567-e89b-12d3-a456-426614174000",
    "triggerAgentId": "complaint-agent",
    "severity": "INFO",
    "agents": [
      "complaint-agent",
      "complaint-agent-categorization"
    ],
    "messages": [
      {
        "timestamp": "2025-01-15T10:30:27.167Z",
        "severity": "INFO",
        "message": "Session started",
        "agentId": "complaint-agent",
        "agentVersion": 3,
        "requestId": "req-123e4567-e89b-12d3-a456-426614174000",
        "isBusinessLog": false
      },
      {
        "timestamp": "2025-01-15T10:30:28.234Z",
        "severity": "INFO",
        "message": "Handed off to categorization agent",
        "agentId": "complaint-agent",
        "agentVersion": 3,
        "requestId": "req-123e4567-e89b-12d3-a456-426614174000",
        "isBusinessLog": true
      }
    ],
    "duration": 120,
    "promptTokens": 2468,
    "completionTokens": 890,
    "metadata": {
      "version": 1,
      "createdAt": "2025-01-15T10:30:27.167Z",
      "modifiedAt": "2025-01-15T10:30:29.234Z"
    }
  }
]

Retrieving agent session by ID

get

Retrieves the agent session by given ID.

Required scopes

This endpoint requires the following scopes:

• : Needed to read AI agents.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstringRequired

Your Emporix tenant name.

Note: The tenant name should always be provided in lowercase.

sessionIdstringRequired

Query parameters

fieldsstringOptional

Fields to be returned in the response.

Responses

200

A single agent session.

application/json

sessionIdstringOptional

Unique identifier of the session.

triggerAgentIdstringOptional

Unique identifier of the agent that triggered the session.

severitystring · enumOptional

Severity level of the log entry.

Possible values:

agentsstring[]Optional

List of agent IDs that participated in this session.

durationinteger · int64Optional

Duration of the session in seconds.

promptTokensinteger · int64Optional

Cumulative LLM prompt token count for this session.

completionTokensinteger · int64Optional

Cumulative LLM completion token count for this session.

401

The authorization token is invalid or has expired.

application/json

403

Authorization scopes of the access token are not sufficient and do not match the scopes required by the endpoint.

application/json

404

Example response

application/json

get/ai-service/{tenant}/agentic/logs/sessions/{sessionId}

GET /ai-service/{tenant}/agentic/logs/sessions/{sessionId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "sessionId": "sess-123e4567-e89b-12d3-a456-426614174000",
  "triggerAgentId": "complaint-agent",
  "severity": "INFO",
  "agents": [
    "complaint-agent",
    "complaint-agent-categorization"
  ],
  "messages": [
    {
      "timestamp": "2025-01-15T10:30:28.234Z",
      "severity": "INFO",
      "message": "Retrieved order details successfully",
      "agentId": "complaint-agent",
      "agentVersion": 3,
      "requestId": "req-123e4567-e89b-12d3-a456-426614174000",
      "isBusinessLog": true
    },
    {
      "timestamp": "2025-01-15T10:30:30.789Z",
      "severity": "INFO",
      "message": "Categorization agent processing request",
      "agentId": "complaint-agent-categorization",
      "agentVersion": 2,
      "requestId": "req-123e4567-e89b-12d3-a456-426614174000",
      "isBusinessLog": false
    }
  ],
  "duration": 120,
  "promptTokens": 2468,
  "completionTokens": 890,
  "metadata": {
    "version": 1,
    "createdAt": "2025-01-15T10:30:27.167Z",
    "modifiedAt": "2025-01-15T10:30:30.789Z"
  }
}

Searching agent sessions

post

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.

Required scopes

This endpoint requires the following scopes:

• : Needed to read AI agents.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstringRequired

Your Emporix tenant name.

Note: The tenant name should always be provided in lowercase.

Query parameters

pageSizestringOptional

The number of documents to be retrieved per page.

pageNumberstringOptional

The page number to be retrieved. The size of the pages should be specified by the pageSize parameter.

nextstring · max: 4096Optional

Opaque cursor from the X-Next-Cursor response header. Use it to retrieve the next set of results. Cannot be combined with prev in the same request; sending both returns 400 Bad Request. When 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).

prevstring · max: 4096Optional

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.

sortstringOptional

List of properties used to sort the results, separated by colons.

fieldsstringOptional

Fields to be returned in the response.

Header parameters

X-Total-CountbooleanOptional

Flag indicating whether the total number of retrieved results should be returned.

Body

qstringOptional

A standard query parameter is used to search for specific values.

See: Standard Practices - Query parameter

Responses

200

List of agent sessions.

application/json

400

The request was syntactically incorrect.

application/json

401

The authorization token is invalid or has expired.

application/json

403

Authorization scopes of the access token are not sufficient and do not match the scopes required by the endpoint.

application/json

post/ai-service/{tenant}/agentic/logs/sessions/search

POST /ai-service/{tenant}/agentic/logs/sessions/search HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 23

{
  "q": "name:~Complaint"
}

[
  {
    "sessionId": "sess-123e4567-e89b-12d3-a456-426614174000",
    "triggerAgentId": "complaint-agent",
    "severity": "INFO",
    "agents": [
      "complaint-agent",
      "complaint-agent-categorization"
    ],
    "messages": [
      {
        "timestamp": "2025-01-15T10:30:27.167Z",
        "severity": "INFO",
        "message": "Session started",
        "agentId": "complaint-agent",
        "agentVersion": 3,
        "requestId": "req-123e4567-e89b-12d3-a456-426614174000",
        "isBusinessLog": false
      },
      {
        "timestamp": "2025-01-15T10:30:28.234Z",
        "severity": "INFO",
        "message": "Handed off to categorization agent",
        "agentId": "complaint-agent",
        "agentVersion": 3,
        "requestId": "req-123e4567-e89b-12d3-a456-426614174000",
        "isBusinessLog": true
      }
    ],
    "duration": 120,
    "promptTokens": 2468,
    "completionTokens": 890,
    "metadata": {
      "version": 1,
      "createdAt": "2025-01-15T10:30:27.167Z",
      "modifiedAt": "2025-01-15T10:30:29.234Z"
    }
  }
]