openapi: 3.2.0
info:
  title: Latitude Saved Searches API
  version: v1
  description: Open-source AI agent monitoring platform. Full observability into what's failing in production. Discover underlying issues, get alerts when something breaks and verify your fix worked.
  servers:
  - url: https://api.latitude.so
    description: Production
servers:
- url: https://api.latitude.so
tags:
- name: Saved Searches
paths:
  /v1/projects/{projectSlug}/searches:
    get:
      tags:
      - Saved Searches
      x-fern-sdk-group-name: savedSearches
      x-fern-sdk-method-name: list
      summary: List saved searches
      description: Returns every saved search in the project. The response uses the standard paginated shape; the saved-search list currently fits in a single page (`nextCursor` is always `null`).
      security:
      - ApiKeyAuth: []
      operationId: listSavedSearches
      parameters:
      - schema:
          type: string
          description: Project slug (human-readable identifier)
        required: true
        description: Project slug (human-readable identifier)
        name: projectSlug
        in: path
      responses:
        '200':
          description: List of saved searches
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedSavedSearches'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags:
      - Saved Searches
      x-fern-sdk-group-name: savedSearches
      x-fern-sdk-method-name: create
      summary: Create saved search
      description: Creates a saved search within the project. At least one of `query` or `filters` must be set. The slug is derived from `name`. OAuth-authenticated only.
      security:
      - ApiKeyAuth: []
      operationId: createSavedSearch
      parameters:
      - schema:
          type: string
          description: Project slug (human-readable identifier)
        required: true
        description: Project slug (human-readable identifier)
        name: projectSlug
        in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSavedSearchBody'
      responses:
        '201':
          description: Saved search created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SavedSearch'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/projects/{projectSlug}/searches/{searchSlug}:
    get:
      tags:
      - Saved Searches
      x-fern-sdk-group-name: savedSearches
      x-fern-sdk-method-name: get
      summary: Get saved search
      description: Returns a single saved search by slug.
      security:
      - ApiKeyAuth: []
      operationId: getSavedSearch
      parameters:
      - schema:
          type: string
          description: Project slug (human-readable identifier)
        required: true
        description: Project slug (human-readable identifier)
        name: projectSlug
        in: path
      - schema:
          type: string
          description: Saved-search slug (human-readable identifier within the project).
        required: true
        description: Saved-search slug (human-readable identifier within the project).
        name: searchSlug
        in: path
      responses:
        '200':
          description: Saved search
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SavedSearch'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      tags:
      - Saved Searches
      x-fern-sdk-group-name: savedSearches
      x-fern-sdk-method-name: update
      summary: Update saved search
      description: Updates a saved search. Renaming may regenerate the slug — clients should re-read the response or rely on the `id` for stable references.
      security:
      - ApiKeyAuth: []
      operationId: updateSavedSearch
      parameters:
      - schema:
          type: string
          description: Project slug (human-readable identifier)
        required: true
        description: Project slug (human-readable identifier)
        name: projectSlug
        in: path
      - schema:
          type: string
          description: Saved-search slug (human-readable identifier within the project).
        required: true
        description: Saved-search slug (human-readable identifier within the project).
        name: searchSlug
        in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSavedSearchBody'
      responses:
        '200':
          description: Updated saved search
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SavedSearch'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      tags:
      - Saved Searches
      x-fern-sdk-group-name: savedSearches
      x-fern-sdk-method-name: delete
      summary: Delete saved search
      description: Deletes a saved search by slug.
      security:
      - ApiKeyAuth: []
      operationId: deleteSavedSearch
      parameters:
      - schema:
          type: string
          description: Project slug (human-readable identifier)
        required: true
        description: Project slug (human-readable identifier)
        name: projectSlug
        in: path
      - schema:
          type: string
          description: Saved-search slug (human-readable identifier within the project).
        required: true
        description: Saved-search slug (human-readable identifier within the project).
        name: searchSlug
        in: path
      responses:
        '204':
          description: Saved search deleted
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/projects/{projectSlug}/searches/{searchSlug}/traces:
    get:
      tags:
      - Saved Searches
      x-fern-sdk-group-name: savedSearches
      x-fern-sdk-method-name: listTraces
      summary: List traces matching a saved search
      description: Returns a cursor-paginated page of traces that match the saved search's `query` + `filters`. Each row uses the same `Trace` shape as `listTraces` — use the trace point-lookup endpoints (`getTrace`, `listTraceSpans`, `getTraceSpan`, `listTraceAnnotations`) to drill into individual traces.
      security:
      - ApiKeyAuth: []
      operationId: listSavedSearchTraces
      parameters:
      - schema:
          type: string
          description: Project slug (human-readable identifier)
        required: true
        description: Project slug (human-readable identifier)
        name: projectSlug
        in: path
      - schema:
          type: string
          description: Saved-search slug (human-readable identifier within the project).
        required: true
        description: Saved-search slug (human-readable identifier within the project).
        name: searchSlug
        in: path
      - schema:
          type: string
          description: Opaque cursor returned in a previous response's `nextCursor`. Omit on the first page.
        required: false
        description: Opaque cursor returned in a previous response's `nextCursor`. Omit on the first page.
        name: cursor
        in: query
      - schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 50
          description: Page size. Defaults to 50; max 200.
        required: false
        description: Page size. Defaults to 50; max 200.
        name: limit
        in: query
      - schema:
          type: string
          enum:
          - relevance
          - startTime
          - endTime
          - durationNs
          - tokensTotal
          - costTotalMicrocents
          default: startTime
          description: Field to sort by. Defaults to `startTime`. Pass `relevance` to rank by semantic match against the saved search's query (best match first, then most recent).
        required: false
        description: Field to sort by. Defaults to `startTime`. Pass `relevance` to rank by semantic match against the saved search's query (best match first, then most recent).
        name: sortBy
        in: query
      - schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
          description: Sort direction. Defaults to `desc` (most recent first).
        required: false
        description: Sort direction. Defaults to `desc` (most recent first).
        name: sortDirection
        in: query
      responses:
        '200':
          description: Page of traces
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedTraces'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    FilterSet:
      type: object
      additionalProperties:
        type: array
        items:
          $ref: '#/components/schemas/FilterCondition'
      description: Filter set keyed by field name. Each entry holds an array of conditions ANDed together for that field; field-level groups are also ANDed across the set.
    Trace:
      type: object
      properties:
        organizationId:
          type: string
          description: Organization that owns this trace.
        projectId:
          type: string
          description: Project this trace belongs to.
        traceId:
          type: string
          description: 32-character trace identifier.
        spanCount:
          type: integer
          minimum: 0
          description: Total number of spans in the trace.
        errorCount:
          type: integer
          minimum: 0
          description: Number of spans flagged with an error status.
        startTime:
          type: string
          description: ISO-8601 timestamp of the trace's earliest span.
        endTime:
          type: string
          description: ISO-8601 timestamp of the trace's latest span.
        durationNs:
          type: number
          description: Wall-clock duration of the trace in nanoseconds.
        timeToFirstTokenNs:
          type: number
          description: Nanoseconds from the start of the first LLM span to its first emitted token. `0` if not measured.
        tokensInput:
          type: number
          description: Total input tokens across LLM spans.
        tokensOutput:
          type: number
          description: Total output tokens across LLM spans.
        tokensCacheRead:
          type: number
          description: Total tokens served from the provider's prompt cache.
        tokensCacheCreate:
          type: number
          description: Total tokens written to the provider's prompt cache.
        tokensReasoning:
          type: number
          description: Total reasoning tokens reported by the model.
        tokensTotal:
          type: number
          description: Sum of all token counters.
        costInputMicrocents:
          type: number
          description: Cost of input tokens in microcents (100,000,000 per USD).
        costOutputMicrocents:
          type: number
          description: Cost of output tokens in microcents (100,000,000 per USD).
        costTotalMicrocents:
          type: number
          description: Total cost in microcents (100,000,000 per USD).
        sessionId:
          type: string
          nullable: true
          description: Conversation/session identifier set by the SDK. `null` when absent.
        userId:
          type: string
          nullable: true
          description: End-user identifier set by the SDK. `null` when absent.
        simulationId:
          type: string
          nullable: true
          description: CUID of the simulation that produced this trace. `null` when not a simulation.
        tags:
          type: array
          items:
            type: string
          description: Free-form tags attached at ingest time.
        models:
          type: array
          items:
            type: string
          description: Model identifiers seen across the trace's LLM spans.
        providers:
          type: array
          items:
            type: string
          description: LLM-provider identifiers seen across the trace's spans.
        serviceNames:
          type: array
          items:
            type: string
          description: OpenTelemetry `service.name` values seen in the trace.
        rootSpanId:
          type: string
          nullable: true
          description: Identifier of the trace's root span. `null` when no root span has been ingested.
        rootSpanName:
          type: string
          nullable: true
          description: '`name` attribute of the root span. `null` when no root span has been ingested.'
        positiveAnnotationCount:
          type: integer
          minimum: 0
          description: Number of `passed = true` annotations attached to this trace.
        negativeAnnotationCount:
          type: integer
          minimum: 0
          description: Number of `passed = false` annotations attached to this trace.
      required:
      - organizationId
      - projectId
      - traceId
      - spanCount
      - errorCount
      - startTime
      - endTime
      - durationNs
      - timeToFirstTokenNs
      - tokensInput
      - tokensOutput
      - tokensCacheRead
      - tokensCacheCreate
      - tokensReasoning
      - tokensTotal
      - costInputMicrocents
      - costOutputMicrocents
      - costTotalMicrocents
      - sessionId
      - userId
      - simulationId
      - tags
      - models
      - providers
      - serviceNames
      - rootSpanId
      - rootSpanName
      - positiveAnnotationCount
      - negativeAnnotationCount
    Error:
      type: object
      properties:
        error:
          type: string
      required:
      - error
    FilterCondition:
      type: object
      properties:
        op:
          type: string
          enum:
          - eq
          - neq
          - gt
          - gte
          - lt
          - lte
          - in
          - notIn
          - contains
          - notContains
          - gtePercentile
          description: Comparison operator applied to the field's value (e.g. `eq`, `neq`, `in`). The full operator list lives in the API reference.
        value:
          anyOf:
          - type: string
          - type: number
          - type: boolean
          - type: array
            items:
              anyOf:
              - type: string
              - type: number
          description: Right-hand value compared against the field. Arrays are required for `in` / `notIn`-style operators.
      required:
      - op
      - value
    CreateSavedSearchBody:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: Human-readable name. Used to derive the slug.
        query:
          type: string
          nullable: true
          maxLength: 500
          default: null
          description: Free-text semantic query. `null` (default) when the search is filter-only. At least one of `query` or `filters` must be set.
        filters:
          allOf:
          - $ref: '#/components/schemas/FilterSet'
          - description: Structured filter set. Defaults to `{}` (no filters). At least one of `query` or `filters` must be set.
      required:
      - name
    PaginatedSavedSearches:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/SavedSearch'
          description: Page of items, in the requested sort order.
        nextCursor:
          type: string
          nullable: true
          description: Opaque cursor for fetching the next page. `null` when there are no more pages. Pass it back in `cursor` to continue.
        hasMore:
          type: boolean
          description: '`true` when there is at least one more page after this one.'
      required:
      - items
      - nextCursor
      - hasMore
    PaginatedTraces:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Trace'
          description: Page of items, in the requested sort order.
        nextCursor:
          type: string
          nullable: true
          description: Opaque cursor for fetching the next page. `null` when there are no more pages. Pass it back in `cursor` to continue.
        hasMore:
          type: boolean
          description: '`true` when there is at least one more page after this one.'
      required:
      - items
      - nextCursor
      - hasMore
    SavedSearch:
      type: object
      properties:
        id:
          type: string
          minLength: 24
          maxLength: 24
          description: Stable saved-search identifier.
        organizationId:
          type: string
          minLength: 24
          maxLength: 24
          description: Organization that owns this saved search.
        projectId:
          type: string
          minLength: 24
          maxLength: 24
          description: Project this saved search belongs to.
        slug:
          type: string
          description: URL-safe slug derived from `name`. Regenerated when the name changes in a way that affects the slug.
        name:
          type: string
          description: Human-readable name.
        query:
          type: string
          nullable: true
          description: Free-text semantic query applied alongside `filters`. `null` when the search is filter-only. At least one of `query` or `filters` must be set.
        filters:
          allOf:
          - $ref: '#/components/schemas/FilterSet'
          - description: Structured filter set applied alongside `query`. Empty object means filter-free. At least one of `query` or `filters` must be set.
        deletedAt:
          type: string
          nullable: true
          description: ISO-8601 timestamp at which the search was deleted. `null` while active.
        createdAt:
          type: string
          description: ISO-8601 timestamp of creation.
        updatedAt:
          type: string
          description: ISO-8601 timestamp of the last update.
      required:
      - id
      - organizationId
      - projectId
      - slug
      - name
      - query
      - filters
      - deletedAt
      - createdAt
      - updatedAt
    UpdateSavedSearchBody:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: New human-readable name. Triggers slug regeneration when the change affects the slug form (cosmetic edits like capitalization keep the URL stable).
        query:
          type: string
          nullable: true
          maxLength: 500
          description: Replace the free-text query. Pass `null` to clear it.
        filters:
          allOf:
          - $ref: '#/components/schemas/FilterSet'
          - description: Replace the structured filter set.
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: 'Organization-scoped API key, sent as `Authorization: Bearer <key>`.'
      x-fern-bearer:
        name: apiKey
        env: LATITUDE_API_KEY