> ## Documentation Index
> Fetch the complete documentation index at: https://docs.promptlayer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Request Logs

Search logged requests using structured filters, free-text search, sorting, and pagination. This endpoint is useful for analytics, debugging, data export, and custom dashboards.

## Behavior Notes

* This endpoint is rate limited to 10 requests per minute.
* Results are capped at 25 items per page.
* Use `filter_group` for structured filters and `q` for fuzzy prefix search across prompt input and LLM output text.
* Search indexing, nested fields, and operator behavior are explained in [Search Data Model](/features/prompt-history/search-data-model).

## Related

* [Search Request Suggestions](/reference/search-request-suggestions)
* [Request Analytics](/reference/request-analytics)
* [Search Data Model](/features/prompt-history/search-data-model)


## OpenAPI

````yaml POST /api/public/v2/requests/search
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers: []
security:
  - ApiKeyAuth: []
paths:
  /api/public/v2/requests/search:
    post:
      tags:
        - tracking
      summary: Search Request Logs
      operationId: searchRequestLogs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequestLogsRequest'
            examples:
              expensiveRequests:
                summary: Find expensive requests
                value:
                  filter_group:
                    logic: AND
                    filters:
                      - field: cost
                        operator: gte
                        value: 0.1
                      - field: request_start_time
                        operator: after
                        value: '2025-03-14T00:00:00Z'
                  sort_by: cost
                  sort_order: desc
              metadata:
                summary: Search by metadata
                value:
                  filter_group:
                    logic: AND
                    filters:
                      - field: metadata
                        operator: key_equals
                        value: customer_123
                        nested_key: user_id
              paginated:
                summary: Paginate through results
                value:
                  filter_group:
                    logic: AND
                    filters:
                      - field: engine
                        operator: is
                        value: gpt-4o
                  page: 3
                  per_page: 25
                  sort_by: request_start_time
                  sort_order: desc
      responses:
        '200':
          description: Paginated list of matching request logs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchRequestLogsResponse'
              examples:
                results:
                  summary: Search results
                  value:
                    success: true
                    items:
                      - id: 12345
                        engine: gpt-4o
                        provider_type: openai
                        input_tokens: 150
                        output_tokens: 300
                        price: 0.005
                        request_start_time: '2025-03-15T10:30:00Z'
                        request_end_time: '2025-03-15T10:30:01Z'
                        latency: 1.234
                        tags_array:
                          - production
                        metadata:
                          - user_id: customer_123
                        scores: []
                        prompt_name: support-response
                    page: 1
                    pages: 5
                    per_page: 25
                    total: 112
                    has_next: true
                    has_prev: false
                    next_num: 2
                    prev_num: null
        '400':
          description: Invalid filter or search parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
components:
  schemas:
    SearchRequestLogsRequest:
      title: SearchRequestLogsRequest
      description: >-
        Search and filter request logs with structured filters, free-text
        search, sorting, and pagination. Extends `RequestLogQuery` with
        pagination and `include_prompt_name`.
      allOf:
        - $ref: '#/components/schemas/RequestLogQuery'
        - type: object
          properties:
            page:
              type: integer
              minimum: 1
              nullable: true
              description: Page number for pagination. Defaults to 1.
            per_page:
              type: integer
              minimum: 1
              maximum: 25
              nullable: true
              description: Number of results per page. Defaults to 10, maximum 25.
            include_prompt_name:
              type: boolean
              nullable: true
              description: >-
                When true, includes the prompt template name in each result
                item. Defaults to false.
      example:
        filter_group:
          logic: AND
          filters:
            - field: cost
              operator: gte
              value: 0.1
        page: 1
        per_page: 25
        sort_by: cost
        sort_order: desc
    SearchRequestLogsResponse:
      type: object
      title: SearchRequestLogsResponse
      description: Paginated search results.
      properties:
        success:
          type: boolean
          description: Indicates the request was successful.
        items:
          type: array
          description: List of matching request log summaries.
          items:
            $ref: '#/components/schemas/RequestLogSearchResult'
        page:
          type: integer
          description: Current page number.
        pages:
          type: integer
          description: Total number of pages.
        per_page:
          type: integer
          description: Number of results per page.
        total:
          type: integer
          description: Total number of matching results.
        has_next:
          type: boolean
          description: Whether there are more pages after the current one.
        has_prev:
          type: boolean
          description: Whether there are pages before the current one.
        next_num:
          type: integer
          nullable: true
          description: Next page number, or null if on the last page.
        prev_num:
          type: integer
          nullable: true
          description: Previous page number, or null if on the first page.
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          default: false
          description: Indicates that the request failed.
        message:
          type: string
          description: Human-readable error message.
        error:
          type: string
          description: Machine-readable or fallback error message.
      additionalProperties: true
      description: >-
        Standard error response. Some legacy endpoints may return either message
        or error.
    RequestLogQuery:
      type: object
      title: RequestLogQuery
      description: >-
        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`.
      properties:
        filter_group:
          $ref: '#/components/schemas/StructuredFilterGroup'
          nullable: true
          description: Nested filter group with AND/OR logic. Use this for complex queries.
        q:
          type: string
          nullable: true
          description: >-
            Free-text search query. Searches across the prompt input and LLM
            output text using fuzzy prefix matching.
        sort_by:
          type: string
          nullable: true
          enum:
            - request_start_time
            - input_tokens
            - output_tokens
            - cost
            - latency_ms
            - status
          description: >-
            Field to sort results by. Does not affect aggregated output for
            `/requests/analytics`.
        sort_order:
          type: string
          nullable: true
          enum:
            - asc
            - desc
          description: Sort direction. Must be provided together with sort_by.
      example:
        filter_group:
          logic: AND
          filters:
            - field: engine
              operator: is
              value: gpt-4o
        sort_by: request_start_time
        sort_order: desc
    RequestLogSearchResult:
      type: object
      title: RequestLogSearchResult
      additionalProperties: true
      properties:
        id:
          type: integer
        engine:
          type: string
        provider_type:
          type: string
        input_tokens:
          type: integer
        output_tokens:
          type: integer
        price:
          type: number
        request_start_time:
          type: string
          format: date-time
        request_end_time:
          type: string
          format: date-time
        latency:
          type: number
        tags_array:
          type: array
          items:
            type: string
        metadata:
          type: array
          items:
            additionalProperties: true
            type: object
        scores:
          type: array
          items:
            additionalProperties: true
            type: object
        prompt_name:
          type: string
          nullable: true
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    StructuredFilterGroup:
      type: object
      title: StructuredFilterGroup
      description: >-
        A group of filters combined with AND or OR logic. Can be nested
        recursively.
      required:
        - filters
      properties:
        logic:
          type: string
          enum:
            - AND
            - OR
          default: AND
          description: How to combine the filters in this group.
        filters:
          type: array
          description: List of filters or nested filter groups.
          items:
            oneOf:
              - $ref: '#/components/schemas/StructuredFilter'
              - $ref: '#/components/schemas/StructuredFilterGroup'
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    StructuredFilter:
      type: object
      title: StructuredFilter
      description: A single filter condition on a request log field.
      required:
        - field
        - operator
      properties:
        field:
          type: string
          description: The request log field to filter on.
          enum:
            - 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
        operator:
          type: string
          description: The comparison operator.
          enum:
            - 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
        value:
          description: >-
            The value to compare against. Type depends on the field and
            operator.
          oneOf:
            - type: string
            - type: number
            - type: boolean
            - type: array
            - type: 'null'
        nested_key:
          type: string
          nullable: true
          description: >-
            Required for nested fields (metadata, output, input_variables).
            Specifies which key within the nested object to filter on.
  responses:
    UnauthorizedError:
      description: Unauthorized - missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ForbiddenError:
      description: Forbidden - API key does not have access to the requested resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ValidationError:
      description: Validation error - request parameters or body are invalid.
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/HTTPValidationError'
              - $ref: '#/components/schemas/ErrorResponse'
    TooManyRequestsError:
      description: Too many requests - the endpoint rate limit was exceeded.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            rateLimited:
              summary: Rate limited
              value:
                success: false
                message: Rate limit exceeded. Please retry later.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY

````