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

# Get Trace Logs

> Fetches trace logs and returns them as a paginated response.

<RequestExample>
  ```bash curl theme={null}
  curl --request POST \
    --url https://parea-ai-backend-us-9ac16cdbc7a7b006.onporter.run/api/parea/v1/get_trace_logs \
    --header 'Content-Type: application/json' \
    --header 'x-user-id: <api-key>' \
    --data '{
        "project_name": "default",
        "filter_field": "trace_name",
        "filter_operator": "like",
        "filter_value": "llm"
    }'
  ```

  ```python Python theme={null}
  from parea import Parea
  from parea.schemas import FilterOperator, QueryParams

  p = Parea(api_key="PAREA_API_KEY")
  response = p.get_trace_logs(
      QueryParams(
          project_name="default",
          filter_field="trace_name",
          filter_operator=FilterOperator.LIKE,
          filter_value="llm"
      )
  )
  ```

  ```typescript TypeScript theme={null}
  import { PaginatedTraceLogsResponse, Parea } from 'parea-ai';

  const p = new Parea(process.env.PAREA_API_KEY);

  const response: PaginatedTraceLogsResponse = await p.getTraceLogs({
    project_name: 'default',
    filter_field: 'trace_name',
    filter_operator: 'like',
    filter_value: 'llm',
  });
  ```
</RequestExample>


## OpenAPI

````yaml post /api/parea/v1/get_trace_logs
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers: []
security: []
paths:
  /api/parea/v1/get_trace_logs:
    post:
      summary: Get Trace Logs Api
      description: Fetches trace logs and returns them as a paginated response.
      operationId: get_trace_logs_api_api_parea_v1_get_trace_logs_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryParamsPaginationPublic'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse_TraceLogTreeSchema_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
        - APIKeyHeader: []
        - APIKeyHeader: []
components:
  schemas:
    QueryParamsPaginationPublic:
      properties:
        page:
          type: integer
          exclusiveMinimum: 0
          title: Page
          description: Page number starting from 1
          default: 1
        page_size:
          type: integer
          maximum: 100000
          exclusiveMinimum: 0
          title: Page Size
          description: Number of items per page
          default: 20
        filter_field:
          anyOf:
            - type: string
            - type: 'null'
          title: Filter Field
          description: >-
            Field to filter on.

            If you want to filter by a score, you need to follow this format:
            'score:{score_name}'.

            If you want to filter by annotation, you need to follow this format:
            'annotation:{annotation_type}:{annotation_id}'.
        filter_key:
          anyOf:
            - type: string
            - type: 'null'
          title: Filter Key
          description: Filter by key when filtering on a map
        filter_operator:
          anyOf:
            - $ref: '#/components/schemas/FilterOperator'
            - type: 'null'
          description: Filter operator
        filter_value:
          anyOf:
            - type: string
            - type: 'null'
          title: Filter Value
          description: Filter value
        project_name:
          type: string
          title: Project Name
          description: Filter by project name
        time_range:
          allOf:
            - $ref: '#/components/schemas/TimeRange'
          description: 'Time range for the logs: 1h,3h,6h,24h, 7d, 1m, 3m, 1y or na'
          default: na
        status:
          anyOf:
            - type: string
            - type: 'null'
          title: Status
          description: 'Filter by status: success, error'
      type: object
      required:
        - project_name
      title: QueryParamsPaginationPublic
      examples:
        - filter_field: trace_name
          filter_operator: like
          filter_value: llm
    PaginatedResponse_TraceLogTreeSchema_:
      properties:
        total:
          type: integer
          title: Total
        page:
          type: integer
          title: Page
        total_pages:
          type: integer
          title: Total Pages
        page_size:
          type: integer
          title: Page Size
        results:
          items:
            $ref: '#/components/schemas/TraceLogTreeSchema'
          type: array
          title: Results
      type: object
      required:
        - total
        - page
        - total_pages
        - page_size
        - results
      title: PaginatedResponse[TraceLogTreeSchema]
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    FilterOperator:
      type: string
      enum:
        - equals
        - not_equals
        - like
        - greater_than_or_equal
        - less_than_or_equal
        - greater_than
        - less_than
        - is_null
        - exists
        - in
        - between
      title: FilterOperator
    TimeRange:
      type: string
      enum:
        - na
        - 1h
        - 3h
        - 6h
        - 24h
        - 7d
        - 1m
        - 3m
        - 6m
        - 1y
      title: TimeRange
    TraceLogTreeSchema:
      properties:
        configuration:
          allOf:
            - $ref: '#/components/schemas/InputsSchema-Output'
          description: >-
            If this log was a LLM call, this will contain the configuration used
            for the call.
          default: {}
        inputs:
          anyOf:
            - type: object
            - type: 'null'
          title: Inputs
          description: >-
            Key-value pair inputs of this trace. Note, there is a special field
            to capture messages in LLM calls. You can still use it in the case
            of LLM calls to track the key-value pairs for prompt templates.
        output:
          anyOf:
            - type: string
            - type: 'null'
          title: Output
          description: >-
            Response of this step/log/function. If response isn’t a string, it
            needs to be serialized to a string.
        target:
          anyOf:
            - type: string
            - type: 'null'
          title: Target
          description: "The target or “gold standardâ€\x9D response for the inputs of this log."
        latency:
          anyOf:
            - type: number
            - type: 'null'
          title: Latency
          description: Latency of this log in seconds.
          default: 0
        time_to_first_token:
          anyOf:
            - type: number
            - type: 'null'
          title: Time To First Token
          description: >-
            If this was a LLM call, this will contain the time taken to generate
            the first token.
        input_tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Input Tokens
          description: >-
            If this was a LLM call, this will contain the number of tokens in
            the input.
          default: 0
        output_tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Output Tokens
          description: >-
            If this was a LLM call, this will contain the number of tokens in
            the output.
          default: 0
        total_tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Total Tokens
          description: >-
            If this was a LLM call, this will contain the total number of tokens
            in the input and output.
          default: 0
        cost:
          anyOf:
            - type: number
            - type: 'null'
          title: Cost
          description: If this was a LLM call, this will contain the cost of the call.
          default: 0
        trace_id:
          type: string
          title: Trace Id
          description: 'UUID of the trace log. Ex: e3267953-a16f-47f5-b37e-622dbb29d730'
        start_timestamp:
          type: string
          title: Start Timestamp
          description: Start timestamp
        parent_trace_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Parent Trace Id
          description: >-
            If given, current trace will be a child of this trace. If current
            child is not a child, `parent_trace_id` should be equal to
            `trace_id`
        root_trace_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Root Trace Id
          description: >-
            This is the UUID of the root trace/span of this trace. If current
            trace is the root trace, `root_trace_id` must be equal to `trace_id`
        project_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Project Name
          description: >-
            Name of the project with which the trace/log should be associated
            with. Must be provided if `project_uuid` is not provided
        status:
          anyOf:
            - type: string
            - type: 'null'
          title: Status
          description: If the trace was a `success` or `error`
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
          description: >-
            If `status=error`, this should contain any additional information
            such as the stacktrace
        output_for_eval_metrics:
          anyOf:
            - type: string
            - type: 'null'
          title: Output For Eval Metrics
          description: >-
            If provided, will be used as output for any specified evaluation
            metric.
        evaluation_metric_names:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Evaluation Metric Names
          description: >-
            Names of evaluation metrics deployed on Parea which should be
            applied to this log.
        scores:
          anyOf:
            - items:
                $ref: '#/components/schemas/EvaluationScoreSchema'
              type: array
            - type: 'null'
          title: Scores
          description: Any scores/eval results associated with this log.
        feedback_score:
          anyOf:
            - type: number
            - type: 'null'
          title: Feedback Score
          description: Any captured (user) feedback on this log
        apply_eval_frac:
          anyOf:
            - type: number
            - type: 'null'
          title: Apply Eval Frac
          description: >-
            If specified, evals given with `evaluation_metric_names` will be
            applied to this log with this fraction.
          default: 1
        log_sample_rate:
          anyOf:
            - type: number
              maximum: 1
              minimum: 0
            - type: 'null'
          title: Log Sample Rate
          description: >-
            If specified, this log and its entire associated trace will logged
            with this probability. Must be between 0 and 1 (incl.). Defaults to
            1.0 (i.e., keeping all logs)
          default: 1
        deployment_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Deployment Id
          description: Optionally, provide the ID of the used deployed prompt in this log.
        cache_hit:
          type: boolean
          title: Cache Hit
          description: If the cache was hit for this log.
          default: false
        trace_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Trace Name
          description: The name of this span.
        children:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Children
          description: UUIDs of any children.
        children_ids:
          anyOf:
            - items:
                type: integer
              type: array
            - type: 'null'
          title: Children Ids
          description: IDs of any children. Will be automatically populated.
        end_timestamp:
          anyOf:
            - type: string
            - type: 'null'
          title: End Timestamp
          description: End timestamp of span.
        end_user_identifier:
          anyOf:
            - type: string
            - type: 'null'
          title: End User Identifier
          description: Unique identifier for a end-user.
        session_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Session Id
          description: >-
            Unique identifier for a session. Can you be used to associated
            multiple logs in e.g. chat applications.
        metadata:
          anyOf:
            - type: object
            - type: 'null'
          title: Metadata
          description: >-
            Any additional key-value pairs which provide context or are useful
            for filtering.
        tags:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Tags
          description: >-
            List of tags which provide additional context or are useful for
            filtering.
        experiment_uuid:
          anyOf:
            - type: string
            - type: 'null'
          title: Experiment Uuid
          description: If given, will be used to associate this log with an experiment.
        images:
          anyOf:
            - items:
                $ref: '#/components/schemas/TraceLogImage'
              type: array
            - type: 'null'
          title: Images
          description: Any images associated with trace.
        comments:
          anyOf:
            - items:
                $ref: '#/components/schemas/TraceLogCommentSchema'
              type: array
            - type: 'null'
          title: Comments
          description: Any comments on log which were collected on Parea frontend.
        annotations:
          anyOf:
            - additionalProperties:
                additionalProperties:
                  $ref: '#/components/schemas/TraceLogAnnotationSchema'
                type: object
              type: object
            - type: 'null'
          title: Annotations
          description: >-
            Any annotations on log which were collected on Parea frontend. It
            maps annoation criterion ID to a dictionary mapping user_id (Parea
            user ID) to annotation.
        depth:
          type: integer
          title: Depth
          description: >-
            Depth/level of nestedness of span in overall trace. Root-level trace
            is 0 and it always increments by 1.
          default: 0
        execution_order:
          type: integer
          title: Execution Order
          description: >-
            The execution number of span in trace. It starts with 0 and
            increments by 1 with every span.
          default: 0
        evaluation_metric_ids:
          anyOf:
            - items:
                type: integer
              type: array
            - type: 'null'
          title: Evaluation Metric Ids
          description: Deprecated
        fill_children:
          type: boolean
          title: Fill Children
          description: Deprecated
          default: false
        project_uuid:
          anyOf:
            - type: string
            - type: 'null'
          title: Project Uuid
          description: >-
            UUID of project with which this log is associated. Will be
            automatically filled-in by SDKs
        organization_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Organization Id
          description: >-
            Organization ID associated with Parea API key. Will be automatically
            determined from API key
        children_logs:
          items:
            $ref: '#/components/schemas/TraceLogTreeSchema'
          type: array
          title: Children Logs
          description: Children logs
      type: object
      required:
        - trace_id
        - start_timestamp
      title: TraceLogTreeSchema
      examples:
        - depth: 0
          end_timestamp: '2024-05-30 13:48:35'
          execution_order: 0
          inputs:
            x: Golang
            'y': Fiber
          metadata:
            purpose: testing
          output: Some logged output
          parent_trace_id: <<SAME_UUID>>
          project_name: default
          root_trace_id: <<SAME_UUID>>
          start_timestamp: '2024-05-30 13:48:34'
          status: success
          trace_id: <<UUID>>
          trace_name: test
        - configuration:
            messages:
              - content: Some prompt
                role: user
            model: gpt-4o
            provider: openai
          depth: 0
          end_timestamp: '2024-05-30 13:48:35'
          execution_order: 0
          inputs:
            promptTemplateVar1: value
            promptTemplateVar2: some other value
          metadata:
            purpose: testing
          output: LLM response
          parent_trace_id: <<SAME_UUID>>
          project_name: default
          root_trace_id: <<SAME_UUID>>
          start_timestamp: '2024-05-30 13:48:34'
          status: success
          trace_id: <<UUID>>
          trace_name: LLM
    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
    InputsSchema-Output:
      properties:
        model:
          anyOf:
            - type: string
            - type: 'null'
          title: Model
          description: Model name
        provider:
          anyOf:
            - type: string
            - type: 'null'
          title: Provider
          description: Provider name
        model_params:
          anyOf:
            - $ref: '#/components/schemas/ParamsSchema'
            - type: 'null'
          description: Parameters such as temperature.
        messages:
          anyOf:
            - items:
                $ref: '#/components/schemas/MessageSchema'
              type: array
            - type: 'null'
          title: Messages
          description: Messages to LLM
        functions:
          anyOf:
            - items: {}
              type: array
            - type: 'null'
          title: Functions
          description: >-
            A list of functions the model may generate JSON inputs for. Assumes
            every item in list has key 'name', 'description' and 'parameters'
        function_call:
          anyOf:
            - type: string
            - type: object
            - type: 'null'
          title: Function Call
          description: "Controls how the model responds to function calls. “autoâ€\x9D means the model can pick between an end-user or calling a function. To specifying a particular function name use a dictionary with key=“nameâ€\x9D and value=“my_functionâ€\x9D. This will force the model to call that function."
      type: object
      title: InputsSchema
      description: >-
        Inputs for LLM inference such as messages, functions and additional
        parameters.
    EvaluationScoreSchema:
      properties:
        name:
          type: string
          title: Name
          description: Name of the score / evaluation
        score:
          type: number
          title: Score
          description: Value of the score
        evaluation_metric_id:
          anyOf:
            - type: integer
            - type: 'null'
          title: Evaluation Metric Id
          description: >-
            Will be automatically populated if this score was from a deployed
            evaluation metric.
        reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Reason
          description: Reason for this score
      type: object
      required:
        - name
        - score
      title: EvaluationScoreSchema
      examples:
        - name: Answer Matches Target
          reason: The answer is mostly correct but lacks aspect A & B.
          score: 0.8
    TraceLogImage:
      properties:
        url:
          type: string
          title: Url
          description: URL of image
        caption:
          anyOf:
            - type: string
            - type: 'null'
          title: Caption
          description: Caption of image
      type: object
      required:
        - url
      title: TraceLogImage
    TraceLogCommentSchema:
      properties:
        trace_id:
          type: string
          title: Trace Id
          description: Trace ID
        comment:
          type: string
          title: Comment
          description: Comment
        id:
          anyOf:
            - type: string
            - type: integer
          title: Id
          description: Comment ID
        user_id:
          type: string
          title: User Id
          description: User ID
        user_email_address:
          anyOf:
            - type: string
            - type: 'null'
          title: User Email Address
          description: User email address
        created_at:
          type: string
          title: Created At
          description: Comment creation timestamp
      type: object
      required:
        - trace_id
        - comment
        - id
        - user_id
        - created_at
      title: TraceLogCommentSchema
    TraceLogAnnotationSchema:
      properties:
        trace_id:
          type: string
          title: Trace Id
          description: UUID of associated trace
        defined_annotation_id:
          type: integer
          title: Defined Annotation Id
          description: Annotation criterion ID
        score:
          anyOf:
            - type: number
            - type: 'null'
          title: Score
          description: Annotation score
        value:
          anyOf:
            - type: string
            - type: 'null'
          title: Value
          description: Annotation value
        id:
          anyOf:
            - type: string
            - type: integer
            - type: 'null'
          title: Id
          description: Annotation ID
        created_at:
          type: string
          title: Created At
          description: Annotation creation timestamp
        user_id:
          type: string
          title: User Id
          description: Parea user ID
        user_email_address:
          anyOf:
            - type: string
            - type: 'null'
          title: User Email Address
          description: User email address
        annotation_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Annotation Name
          description: Annotation name
      type: object
      required:
        - trace_id
        - defined_annotation_id
        - created_at
        - user_id
      title: TraceLogAnnotationSchema
    ParamsSchema:
      properties:
        model:
          anyOf:
            - type: string
            - type: 'null'
          title: Model
          description: Model name
        temp:
          anyOf:
            - type: number
            - type: 'null'
          title: Temp
          description: Temperature
        top_p:
          anyOf:
            - type: number
            - type: 'null'
          title: Top P
          description: Top p
        frequency_penalty:
          anyOf:
            - type: number
            - type: 'null'
          title: Frequency Penalty
          description: Frequency penalty
        presence_penalty:
          anyOf:
            - type: number
            - type: 'null'
          title: Presence Penalty
          description: Presence penalty
        max_length:
          anyOf:
            - type: integer
            - type: 'null'
          title: Max Length
          description: Max. number of completion tokens
        response_format:
          anyOf:
            - type: object
            - type: 'null'
          title: Response Format
          description: Response format. See OpenAI docs for definition
        safe_prompt:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Safe Prompt
          description: Used for Mistral.
      type: object
      title: ParamsSchema
      description: >-
        Additional parameters to run inference of LLMs, such as temperature,
        top_p, etc.

        Following the OpenAI API format.
    MessageSchema:
      properties:
        content:
          anyOf:
            - type: string
            - items: {}
              type: array
            - type: 'null'
          title: Content
          description: Message content
          default: ''
        role:
          allOf:
            - $ref: '#/components/schemas/Role'
          description: Message role
          default: user
      type: object
      title: MessageSchema
    Role:
      type: string
      enum:
        - user
        - assistant
        - system
        - user
        - assistant
        - function
        - tool
      title: Role
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: x-user-id

````