openapi: 3.2.0
info:
  title: Latitude Imports 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: Imports
paths:
  /v1/projects/{projectSlug}/imports:
    get:
      tags:
      - Imports
      x-fern-sdk-group-name: imports
      x-fern-sdk-method-name: list
      summary: List imports
      description: Returns the project's imports from other observability platforms, newest first. Excludes the run history — fetch a single import for that.
      security:
      - ApiKeyAuth: []
      operationId: listImports
      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 imports
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListImportsResponse'
        '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:
      - Imports
      x-fern-sdk-group-name: imports
      x-fern-sdk-method-name: create
      summary: Create import
      description: Imports historical traces from another observability platform into the project. The import runs in the background, newest traces first.
      security:
      - ApiKeyAuth: []
      operationId: createImport
      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/CreateImportBody'
      responses:
        '201':
          description: Import created and started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Import'
        '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}/imports/{importId}:
    get:
      tags:
      - Imports
      x-fern-sdk-group-name: imports
      x-fern-sdk-method-name: get
      summary: Get import
      description: Returns a single import, including its recent run history.
      security:
      - ApiKeyAuth: []
      operationId: getImport
      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: Import id.
        required: true
        description: Import id.
        name: importId
        in: path
      responses:
        '200':
          description: Import
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportDetail'
        '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}/imports/{importId}/cancel:
    post:
      tags:
      - Imports
      x-fern-sdk-group-name: imports
      x-fern-sdk-method-name: cancel
      summary: Cancel import
      description: Cancels an import that has not finished. Traces already imported are kept, and the import can be retried later.
      security:
      - ApiKeyAuth: []
      operationId: cancelImport
      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: Import id.
        required: true
        description: Import id.
        name: importId
        in: path
      responses:
        '200':
          description: Import cancelled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Import'
        '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}/imports/{importId}/retry:
    post:
      tags:
      - Imports
      x-fern-sdk-group-name: imports
      x-fern-sdk-method-name: retry
      summary: Retry import
      description: Retries a failed, cancelled, or capped import from where it stopped, as a new import that runs in the background. Credentials must be provided again and match the original's region.
      security:
      - ApiKeyAuth: []
      operationId: retryImport
      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: Import id.
        required: true
        description: Import id.
        name: importId
        in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RetryImportBody'
      responses:
        '201':
          description: Retry created and started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Import'
        '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:
    BraintrustImportCredentials:
      type: object
      properties:
        kind:
          type: string
          enum:
          - braintrust
          description: Marks these as Braintrust credentials.
        region:
          type: string
          enum:
          - eu
          - us
          description: Braintrust data plane the organization lives on.
        apiKey:
          type: string
          minLength: 1
          description: Braintrust API key with read access to the project.
      required:
      - kind
      - region
      - apiKey
    ImportRun:
      type: object
      properties:
        status:
          type: string
          enum:
          - succeeded
          - failed
          description: Whether this page of the import was written.
        stats:
          allOf:
          - $ref: '#/components/schemas/ImportStats'
          - description: What this page alone brought in.
        error:
          type: string
          nullable: true
          description: Why this page failed, or `null`.
        startedAt:
          type: string
          description: ISO-8601 timestamp at which the page started.
        finishedAt:
          type: string
          description: ISO-8601 timestamp at which the page ended.
      required:
      - status
      - stats
      - error
      - startedAt
      - finishedAt
    Error:
      type: object
      properties:
        error:
          type: string
      required:
      - error
    Import:
      type: object
      properties:
        id:
          type: string
          minLength: 24
          maxLength: 24
          description: Stable import identifier.
        organizationId:
          type: string
          minLength: 24
          maxLength: 24
          description: Organization that owns this import.
        projectId:
          type: string
          minLength: 24
          maxLength: 24
          description: Latitude project the traces are imported into.
        source:
          type: string
          enum:
          - langfuse
          - langsmith
          - braintrust
          description: Observability platform the import reads from.
        status:
          type: string
          enum:
          - created
          - queued
          - running
          - succeeded
          - capped
          - cancelled
          - failed
          description: Lifecycle state. `created`/`queued`/`running` are in flight; `succeeded` finished cleanly; `capped` stopped at a ceiling with everything before it kept; `cancelled` and `failed` can be retried.
        config:
          $ref: '#/components/schemas/ImportConfig'
        stats:
          $ref: '#/components/schemas/ImportStats'
        error:
          type: string
          nullable: true
          description: Why the import did not finish cleanly, or which ceiling stopped a `capped` one. `status` alone says whether it failed.
        cancelledAt:
          type: string
          nullable: true
          description: ISO-8601 timestamp at which cancellation was requested, or `null`.
        startedAt:
          type: string
          nullable: true
          description: ISO-8601 timestamp at which a worker picked the import up, or `null`.
        finishedAt:
          type: string
          nullable: true
          description: ISO-8601 timestamp at which the import ended, or `null` while in flight.
        createdAt:
          type: string
          description: ISO-8601 timestamp of creation.
        updatedAt:
          type: string
          description: ISO-8601 timestamp of the last update.
      required:
      - id
      - organizationId
      - projectId
      - source
      - status
      - config
      - stats
      - error
      - cancelledAt
      - startedAt
      - finishedAt
      - createdAt
      - updatedAt
    CreateImportBody:
      type: object
      properties:
        credentials:
          $ref: '#/components/schemas/ImportCredentials'
        sourceProjectId:
          type: string
          minLength: 1
          description: Id of the project on the platform to read from.
        sourceProjectName:
          type: string
          minLength: 1
          description: Name of the platform project, shown in Latitude. Defaults to `sourceProjectId`.
        rangeFrom:
          type: string
          format: date-time
          description: ISO-8601 start of the range to import. Defaults to 90 days before `rangeTo`, bounded by the plan's retention.
        rangeTo:
          type: string
          format: date-time
          description: ISO-8601 end of the range to import. Defaults to now.
        maxTraces:
          type: integer
          minimum: 1
          maximum: 100000
          description: Most traces to import, newest first. Each imported trace bills one credit. Defaults to the maximum, 100,000.
        sessionMetadataKey:
          type: string
          description: 'LangSmith only: run metadata key that groups traces into sessions. Defaults to `thread_id`.'
      required:
      - credentials
      - sourceProjectId
    LangfuseImportCredentials:
      type: object
      properties:
        kind:
          type: string
          enum:
          - langfuse
          description: Marks these as Langfuse credentials.
        region:
          type: string
          enum:
          - eu
          - us
          - jp
          - hipaa-us
          description: Langfuse Cloud region the account lives in.
        publicKey:
          type: string
          minLength: 1
          description: Langfuse project public key (`pk-lf-…`).
        secretKey:
          type: string
          minLength: 1
          description: Langfuse project secret key (`sk-lf-…`).
      required:
      - kind
      - region
      - publicKey
      - secretKey
    RetryImportBody:
      type: object
      properties:
        credentials:
          allOf:
          - $ref: '#/components/schemas/ImportCredentials'
          - description: Platform credentials, required again because they are not stored after an import ends. Must use the same region as the original import.
      required:
      - credentials
    ListImportsResponse:
      type: object
      properties:
        imports:
          type: array
          items:
            $ref: '#/components/schemas/Import'
          description: The project's imports, newest first.
      required:
      - imports
    ImportCredentials:
      oneOf:
      - $ref: '#/components/schemas/LangfuseImportCredentials'
      - $ref: '#/components/schemas/LangsmithImportCredentials'
      - $ref: '#/components/schemas/BraintrustImportCredentials'
      discriminator:
        propertyName: kind
        mapping:
          langfuse: '#/components/schemas/LangfuseImportCredentials'
          langsmith: '#/components/schemas/LangsmithImportCredentials'
          braintrust: '#/components/schemas/BraintrustImportCredentials'
      description: Credentials for the platform to import from; `kind` names the platform. Not stored after the import ends.
    LangsmithImportCredentials:
      type: object
      properties:
        kind:
          type: string
          enum:
          - langsmith
          description: Marks these as LangSmith credentials.
        region:
          type: string
          enum:
          - gcp-eu
          - gcp-us
          - gcp-apac
          - aws-us
          description: LangSmith region the account lives in.
        apiKey:
          type: string
          minLength: 1
          description: LangSmith API key (`lsv2_pt_…`).
        workspaceId:
          type: string
          description: Workspace to import from, for accounts with more than one. Omit to use the key's default workspace.
      required:
      - kind
      - region
      - apiKey
    ImportConfig:
      type: object
      properties:
        sourceProjectId:
          type: string
          description: Id of the project on the platform the import reads from.
        sourceProjectName:
          type: string
          description: Name of the platform project, as shown in Latitude.
        sourceRegion:
          type: string
          description: Platform region the import runs against.
        rangeFrom:
          type: string
          description: ISO-8601 start of the imported time range (inclusive).
        rangeTo:
          type: string
          description: ISO-8601 end of the imported time range (exclusive).
        maxTraces:
          type: integer
          description: Most traces this import will bring in, newest first.
        sessionMetadataKey:
          type: string
          nullable: true
          description: 'LangSmith only: run metadata key that groups traces into sessions. `null` elsewhere.'
      required:
      - sourceProjectId
      - sourceProjectName
      - sourceRegion
      - rangeFrom
      - rangeTo
      - maxTraces
      - sessionMetadataKey
      description: What the import was asked to bring in, snapshotted when it was created.
    ImportDetail:
      allOf:
      - $ref: '#/components/schemas/Import'
      - type: object
        properties:
          runs:
            type: array
            items:
              $ref: '#/components/schemas/ImportRun'
            description: Recent pages the import processed, newest first. Bounded, so old pages fall off.
        required:
        - runs
    ImportStats:
      type: object
      properties:
        recordsFetched:
          type: integer
          description: Rows read from the platform, including spans later skipped.
        sessionsImported:
          type: integer
          description: Distinct sessions among the imported traces.
        tracesImported:
          type: integer
          description: Traces imported. One imported trace bills one credit.
        spansImported:
          type: integer
          description: Spans written across all imported traces.
        spansSkipped:
          type: integer
          description: Spans skipped because they carried no usable trace or span id.
      required:
      - recordsFetched
      - sessionsImported
      - tracesImported
      - spansImported
      - spansSkipped
      description: What the import has brought in so far.
  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