---
title: "Search Request Logs"
method: POST
path: "/api/public/v2/requests/search"
tags: ["tracking"]
---

# Search Request Logs

`POST /api/public/v2/requests/search`

## Request body

- SearchRequestLogsRequest — Canonical request-log query payload — the filter / search / sort fields shared by `POST /api/public/v2/requests/search` (which also accepts pagination + `include_prompt_name`) and `POST /api/public/v2/requests/analytics`.
  - `filter_group` StructuredFilterGroup — A group of filters combined with AND or OR logic. Can be nested recursively.
    - `logic` 'AND' | 'OR' — How to combine the filters in this group.
    - `filters` union[], required — List of filters or nested filter groups.
      - union
        - StructuredFilter — A single filter condition on a request log field.
          - `field` 'pl_id' | 'prompt_id' | 'engine' | 'provider_type' | 'input_text' | 'output_text' | 'prompt_version_number' | 'input_tokens' | 'output_tokens' | 'cost' | 'latency_ms' | 'request_start_time' | 'request_end_time' | 'status' | 'is_json' | 'is_tool_call' | 'is_plain_text' | 'tags' | 'metadata_keys' | 'metadata' | 'tool_names' | 'output' | 'output_keys' | 'input_variables' | 'input_variable_keys' | 'user_intent' | 'agent_intent', required — The request log field to filter on. Intent fields are virtual fields that classify request content by tone and do not require any additional logging configuration. `user_intent` classifies the user's message; valid values: `frustrated`, `satisfied`, `curious`. `agent_intent` classifies the agent's response; valid values: `apologetic`, `refusal`, `uncertain`. Intent fields support operators: `is`, `is_not`, `in`, `not_in`.
          - `operator` 'is' | 'is_not' | 'in' | 'not_in' | 'contains' | 'not_contains' | 'starts_with' | 'ends_with' | 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'between' | 'before' | 'after' | 'is_true' | 'is_false' | 'is_empty' | 'is_not_empty' | 'is_null' | 'is_not_null' | 'key_equals' | 'key_not_equals' | 'key_contains', required — The comparison operator.
          - `value` union — The value to compare against. Type depends on the field and operator.
            - string
            - number
            - boolean
          - `nested_key` string, nullable — Required for nested fields (metadata, output, input_variables). Specifies which key within the nested object to filter on.
        - StructuredFilterGroup — recursive
  - `q` string, nullable — Free-text search query. Searches across the prompt input and LLM output text using fuzzy prefix matching.
  - `sort_by` 'request_start_time' | 'input_tokens' | 'output_tokens' | 'cost' | 'latency_ms' | 'status', nullable — Field to sort results by. Does not affect aggregated output for `/requests/analytics`.
  - `sort_order` 'asc' | 'desc', nullable — Sort direction. Must be provided together with sort_by.
  - `metadata_cost_breakdown_key` string, nullable — When provided, the analytics response includes a `metadataValueBreakdown` array with cost and request counts for each value of this metadata key. Omit or pass null to get an aggregate breakdown across the top metadata keys.
  - `page` integer, nullable — Page number for pagination. Defaults to 1.
  - `per_page` integer, nullable — Number of results per page. Defaults to 10, maximum 25.
  - `include_prompt_name` boolean, nullable — When true, includes the prompt template name in each result item. Defaults to false.

## Response `200`

Paginated list of matching request logs.

- SearchRequestLogsResponse — Paginated search results.
  - `success` boolean — Indicates the request was successful.
  - `items` RequestLogSearchResult[] — List of matching request log summaries.
    - `id` integer
    - `engine` string
    - `provider_type` string
    - `input_tokens` integer
    - `output_tokens` integer
    - `price` number
    - `request_start_time` string, date-time
    - `request_end_time` string, date-time
    - `latency` number
    - `tags_array` string[]
    - `metadata` object[]
    - `scores` object[]
    - `prompt_name` string, nullable
  - `page` integer — Current page number.
  - `pages` integer — Total number of pages.
  - `per_page` integer — Number of results per page.
  - `total` integer — Total number of matching results.
  - `has_next` boolean — Whether there are more pages after the current one.
  - `has_prev` boolean — Whether there are pages before the current one.
  - `next_num` integer, nullable — Next page number, or null if on the last page.
  - `prev_num` integer, nullable — Previous page number, or null if on the first page.

## Other responses

- `400` — Invalid filter or search parameters.
- `401` — Unauthorized - missing or invalid API key.
- `403` — Forbidden - API key does not have access to the requested resource.
- `422` — Validation error - request parameters or body are invalid.
- `429` — Too many requests - the endpoint rate limit was exceeded.

---

[API](https://skmtc.dev/promptlayer/apis/promptlayer-api.md) · [All operations](https://skmtc.dev/promptlayer/apis/promptlayer-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/promptlayer/promptlayer-api/revisions/a23093a0a506/schema)