Skip to main content

aip_sdk.land_traces

aip_sdk.land_traces(payloads: list[dict[str, Any]], *, workspace_id: str | None = None, project_id: str | None = None, sut_id: str | None = None, ingest_convention: str | None = None, dataset_name: str | None = None, dataset_id: str | None = None, buffer_id: str | None = None, retention_days: int | None = None, trace_tags: Iterable[TagInput] | None = None, client: APIClient | None = None) -> TraceIngestRun

Trigger ingestion of inline trace payloads into a dataset.

Landing is asynchronous: this returns as soon as the run is accepted. Call TraceIngestRun.wait_until_terminal() on the result (or poll get_ingest_run() by hand) until run_status is terminal to learn the dataset version the traces landed in.

Parameters

  • payloads list[dict[str, Any]]: The raw trace payloads to ingest (e.g. OpenInference/gen_ai/LangSmith spans). Must be non-empty.
  • workspace_id str | None: Workspace to land the traces in. If omitted and project_id is also omitted, falls back to the client's configured default workspace (aip.init(workspace_id=...) / AIP_WORKSPACE_ID). Pass this or project_id, not both: a project already determines its workspace.
  • project_id str | None: Project to associate the landed dataset with.
  • sut_id str | None: System-under-test the traces were produced by.
  • ingest_convention str | None: Source convention to convert the payloads as — one of INGEST_CONVENTIONS, the set this SDK version knows. Naming it overrides detection, so a payload that is not in that convention is dropped rather than re-sniffed. Leave it None to auto-detect per record, which also handles a convention newer than this SDK version.
  • dataset_name str | None: Name for a new dataset to create for these traces.
  • dataset_id str | None: Existing dataset to append the traces to, instead of creating one.
  • buffer_id str | None: Idempotency key, scoped to the resolved workspace_id. Re-landing with the key of a completed run in the same workspace replays that run's outcome instead of duplicating rows; re-landing while the first run is still in flight raises ConflictError. Reusing a buffer_id across a change in which workspace it resolves to (e.g. setting AIP_WORKSPACE_ID for the first time) does not replay the earlier run, since the pair no longer matches.
  • retention_days int | None: Retention window for the raw landed data — one of RETENTION_DAYS. When None, the platform default applies.
  • trace_tags Iterable[TagInput] | None: Optional trace tags to attach to the landed traces, as TraceTagUpsert instances or equivalent dicts.
  • client APIClient | None: Optional API client.

Returns

Raises

  • NoWorkspaceSelectedError: If no workspace is passed and none is configured for the session.
  • InvalidArgumentError: If payloads is empty, ingest_convention is not a recognised convention, retention_days is not a supported window, an trace_tags entry is malformed or the per-request limit is exceeded, or both project_id and workspace_id are given — a project already determines its workspace.
  • AuthError: If credentials are missing or invalid.
  • ForbiddenError: If workspace_id (or the configured default) names a workspace the caller is not a member of.
  • NotFoundError: If dataset_id names no dataset in the landing workspace or project.
  • APIError: If project_id names no project in a workspace the caller belongs to.
  • ConflictError: If a run for buffer_id is already in flight.
  • UnprocessableEntityError: If the payloads or arguments are rejected by the platform.
  • ResponseParseError: If the platform's response does not match this SDK version.