Skip to main content
Glama

list_audit_logs

Read-onlyIdempotent

Retrieve Portkey organization audit log records for a specified time range to review state-changing API requests for compliance or incident investigation. Requires an Enterprise plan.

Instructions

List audit log records for a Portkey organization within a time range (Enterprise plan only; other plans get a permissions error). Each record is a state-changing API request (POST, PUT, or DELETE) with timestamp, method, uri, request_id, user_id, user_type (user or api_key), organisation_id, workspace_id, response_status_code, resource_type, action, client_ip, country, plus request_body, query_params, and request_headers as JSON strings. Use it for compliance or incident review of individual events; use analytics instead for aggregates. Enterprise-gated. Returns 403 on non-Enterprise Portkey plans.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "start_time": "<start_time>",
      "end_time": "<end_time>",
      "organisation_id": "<organisation_id>"
    },
    "name": "list_audit_logs"
  }
}

Input Schema

NameRequiredDescriptionDefault
uriNoFilter by request URI path
actionNoFilter by action type (e.g., 'create', 'update', 'delete')
methodNoFilter by HTTP method of the audited request
countryNoFilter by country derived from the client IP
user_idNoFilter by the ID of the user or API key that made the request
end_timeYesEnd of time range filter (ISO 8601 format, e.g., '2024-01-31T23:59:59Z')
client_ipNoFilter by client IP address
page_sizeNoNumber of results per page (max 100)
user_typeNoFilter by whether the request came from a user or an API key
request_idNoFilter by request ID
start_timeYesStart of time range filter (ISO 8601 format, e.g., '2024-01-01T00:00:00Z')
current_pageNoZero-based page number; the first page is 0
workspace_idNoFilter audit logs by workspace ID
resource_typeNoFilter by resource type (e.g., 'workspace', 'config', 'virtual_key')
organisation_idYesOrganisation ID whose audit logs to list
response_status_codeNoFilter by HTTP response status code (e.g., 200, 403)

Output Schema

NameRequiredDescriptionDefault
okYesCall succeeded
dataNoSuccess payload
errorNoFailure details

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changedv0.16.5
    • changedOutput schema / properties / data / description
      Previous value: -"Structured success payload when ok is true"New value: +"Success payload"
    • changedOutput schema / properties / error / description
      Previous value: -"Structured error payload when ok is false"New value: +"Failure details"
    • changedOutput schema / properties / error / properties / details / description
      Previous value: -"Optional structured error details"New value: +"Extra error details"
    • changedOutput schema / properties / error / properties / message / description
      Previous value: -"Human-readable error message"New value: +"Error message"
    • changedOutput schema / properties / ok / description
      Previous value: -"Whether the tool call succeeded and returned structured data"New value: +"Call succeeded"
  2. Changed2 schema fields changedv1.0.9
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • changedOutput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
  3. Changed14 schema fields changedv0.12.2
    • changedInput schema / properties / action / description
      Previous value: -"Filter by action type (e.g., 'create', 'update', 'delete', 'login')"New value: +"Filter by action type (e.g., 'create', 'update', 'delete')"
    • removedInput schema / properties / actor_id
      Removed value: -{
      -  "description": "Filter by the user ID who performed the action",
      -  "type": "string"
      -}
    • addedInput schema / properties / client_ip
      Added value: +{
      +  "description": "Filter by client IP address",
      +  "type": "string"
      +}
    • addedInput schema / properties / country
      Added value: +{
      +  "description": "Filter by country derived from the client IP",
      +  "type": "string"
      +}
    • addedInput schema / properties / method
      Added value: +{
      +  "description": "Filter by HTTP method of the audited request",
      +  "enum": [
      +    "POST",
      +    "PUT",
      +    "DELETE"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / organisation_id
      Added value: +{
      +  "description": "Organisation ID whose audit logs to list",
      +  "type": "string"
      +}
    • addedInput schema / properties / request_id
      Added value: +{
      +  "description": "Filter by request ID",
      +  "type": "string"
      +}
    • removedInput schema / properties / resource_id
      Removed value: -{
      -  "description": "Filter by specific resource ID",
      -  "type": "string"
      -}
    • changedInput schema / properties / resource_type / description
      Previous value: -"Filter by resource type (e.g., 'user', 'workspace', 'config', 'virtual_key')"New value: +"Filter by resource type (e.g., 'workspace', 'config', 'virtual_key')"
    • addedInput schema / properties / response_status_code
      Added value: +{
      +  "description": "Filter by HTTP response status code (e.g., 200, 403)",
      +  "maximum": 9007199254740991,
      +  "minimum": -9007199254740991,
      +  "type": "integer"
      +}
    • addedInput schema / properties / uri
      Added value: +{
      +  "description": "Filter by request URI path",
      +  "type": "string"
      +}
    • addedInput schema / properties / user_id
      Added value: +{
      +  "description": "Filter by the ID of the user or API key that made the request",
      +  "type": "string"
      +}
    • addedInput schema / properties / user_type
      Added value: +{
      +  "description": "Filter by whether the request came from a user or an API key",
      +  "enum": [
      +    "user",
      +    "api_key"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / required
      Added value: +[
      +  "start_time",
      +  "end_time",
      +  "organisation_id"
      +]
  4. Changed3 schema fields changedv0.11.5
    • changedInput schema / properties / current_page / description
      Previous value: -"Page number for pagination (starts at 1)"New value: +"Zero-based page number; the first page is 0"
    • removedInput schema / properties / current_page / exclusiveMinimum
      Removed value: -0
    • addedInput schema / properties / current_page / minimum
      Added value: +0
  5. Changed3 schema fields changedv0.5.0
    • addedInput schema / properties / current_page / maximum
      Added value: +9007199254740991
    • changedInput schema / properties / current_page / type
      Previous value: -"number"New value: +"integer"
    • changedInput schema / properties / page_size / type
      Previous value: -"number"New value: +"integer"
  6. Addedv1.0.1
  7. Removed
  8. First observed

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/non-destructive, so the description's added value is the plan gating, the 403 outcome on non-Enterprise plans, and the note that request_body, query_params, and request_headers come back as JSON strings rather than objects. It does not disclose ordering, default page size, or retention limits, which keeps it short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded and the sentence order (what it does, what a record contains, when to use it) is logical. However, the Enterprise restriction is stated twice — once parenthetically with "permissions error" and again as "Enterprise-gated. Returns 403..." — which is redundant rather than reinforcing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 16-parameter, 3-required listing tool with a full output schema, the description covers purpose, scope, plan gating, error behavior, record shape, and the aggregate-vs-individual trade-off. The remaining specifics (page defaults, ordering) are already carried by the schema or output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and every filter already carries its own description and, where relevant, an enum, so the schema does the heavy lifting. The description only reinforces the time-range scope and never explains how filters compose (AND semantics) or what unbounded time ranges do, so it adds little beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("List audit log records for a Portkey organization within a time range") and immediately narrows scope by plan (Enterprise only). The second sentence defines exactly what a record is — a state-changing POST/PUT/DELETE call — which distinguishes this from a general request-log tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use ("compliance or incident review of individual events") and an explicit alternative ("use analytics instead for aggregates"). It also flags the precondition that non-Enterprise plans receive a permissions error, so an agent knows the failure is expected rather than a defect.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools