---
title: "Create import"
method: POST
path: "/v1/projects/{projectSlug}/imports"
tags: ["Imports"]
---

# Create import

`POST /v1/projects/{projectSlug}/imports`

Imports historical traces from another observability platform into the project. The import runs in the background, newest traces first.

## Path parameters

- `projectSlug` string, required — Project slug (human-readable identifier)

## Request body

- CreateImportBody
  - `credentials` union, required — Credentials for the platform to import from; `kind` names the platform. Not stored after the import ends.
    - LangfuseImportCredentials
      - `kind` 'langfuse', required — Marks these as Langfuse credentials.
      - `region` 'eu' | 'us' | 'jp' | 'hipaa-us', required — Langfuse Cloud region the account lives in.
      - `publicKey` string, required — Langfuse project public key (`pk-lf-…`).
      - `secretKey` string, required — Langfuse project secret key (`sk-lf-…`).
    - LangsmithImportCredentials
      - `kind` 'langsmith', required — Marks these as LangSmith credentials.
      - `region` 'gcp-eu' | 'gcp-us' | 'gcp-apac' | 'aws-us', required — LangSmith region the account lives in.
      - `apiKey` string, required — LangSmith API key (`lsv2_pt_…`).
      - `workspaceId` string — Workspace to import from, for accounts with more than one. Omit to use the key's default workspace.
    - BraintrustImportCredentials
      - `kind` 'braintrust', required — Marks these as Braintrust credentials.
      - `region` 'eu' | 'us', required — Braintrust data plane the organization lives on.
      - `apiKey` string, required — Braintrust API key with read access to the project.
  - `sourceProjectId` string, required — Id of the project on the platform to read from.
  - `sourceProjectName` string — Name of the platform project, shown in Latitude. Defaults to `sourceProjectId`.
  - `rangeFrom` string, date-time — ISO-8601 start of the range to import. Defaults to 90 days before `rangeTo`, bounded by the plan's retention.
  - `rangeTo` string, date-time — ISO-8601 end of the range to import. Defaults to now.
  - `maxTraces` integer — Most traces to import, newest first. Each imported trace bills one credit. Defaults to the maximum, 100,000.
  - `sessionMetadataKey` string — LangSmith only: run metadata key that groups traces into sessions. Defaults to `thread_id`.

## Response `201`

Import created and started

- Import
  - `id` string, required — Stable import identifier.
  - `organizationId` string, required — Organization that owns this import.
  - `projectId` string, required — Latitude project the traces are imported into.
  - `source` 'langfuse' | 'langsmith' | 'braintrust', required — Observability platform the import reads from.
  - `status` 'created' | 'queued' | 'running' | 'succeeded' | 'capped' | 'cancelled' | 'failed', required — 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` ImportConfig, required — What the import was asked to bring in, snapshotted when it was created.
    - `sourceProjectId` string, required — Id of the project on the platform the import reads from.
    - `sourceProjectName` string, required — Name of the platform project, as shown in Latitude.
    - `sourceRegion` string, required — Platform region the import runs against.
    - `rangeFrom` string, required — ISO-8601 start of the imported time range (inclusive).
    - `rangeTo` string, required — ISO-8601 end of the imported time range (exclusive).
    - `maxTraces` integer, required — Most traces this import will bring in, newest first.
    - `sessionMetadataKey` string, nullable, required — LangSmith only: run metadata key that groups traces into sessions. `null` elsewhere.
  - `stats` ImportStats, required — What the import has brought in so far.
    - `recordsFetched` integer, required — Rows read from the platform, including spans later skipped.
    - `sessionsImported` integer, required — Distinct sessions among the imported traces.
    - `tracesImported` integer, required — Traces imported. One imported trace bills one credit.
    - `spansImported` integer, required — Spans written across all imported traces.
    - `spansSkipped` integer, required — Spans skipped because they carried no usable trace or span id.
  - `error` string, nullable, required — Why the import did not finish cleanly, or which ceiling stopped a `capped` one. `status` alone says whether it failed.
  - `cancelledAt` string, nullable, required — ISO-8601 timestamp at which cancellation was requested, or `null`.
  - `startedAt` string, nullable, required — ISO-8601 timestamp at which a worker picked the import up, or `null`.
  - `finishedAt` string, nullable, required — ISO-8601 timestamp at which the import ended, or `null` while in flight.
  - `createdAt` string, required — ISO-8601 timestamp of creation.
  - `updatedAt` string, required — ISO-8601 timestamp of the last update.

## Other responses

- `400` — Validation error
- `401` — Unauthorized
- `404` — Not found

---

[API](https://skmtc.net/latitude-dev/apis/latitude.md) · [All operations](https://skmtc.net/latitude-dev/apis/latitude/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/latitude-dev/latitude/revisions/6a8789c59a5c/schema)