Skip to main content
For the complete documentation index for agents and LLMs, see llms.txt.

Capture an Indexing Trace with the REST APIBeta

Beta
This is coming — this page describes a feature that's still being rolled out and may not be available to you yet.

To debug indexing results, capture an indexing trace: it shows how a file was converted and split.

About This Task​

Unlike query pipelines, an index doesn't record a trace for every run. You ask for one when you reindex a single file.

Prerequisites​

  • You need an API key. For details, see Generate API Keys.
  • The index must be deployed.

Capture a Trace​

  1. Call the reindex endpoint for a file and set the capture_trace query parameter to true:

    curl --request POST \
      --url "https://api.cloud.deepset.ai/api/v1/workspaces/<WORKSPACE_NAME>/indexes/<INDEX_NAME>/files/<FILE_ID>/reindex?capture_trace=true" \
      --header "Authorization: Bearer <YOUR_API_KEY>"

    The endpoint returns 204 when the file is queued for indexing.

  2. When the run finishes, read the trace with the API:

    • To list the index's traces, newest first, send a GET request to /api/v2/workspaces/{workspace_id}/indexes/{pipeline_index_id}/traces.
    • To read one trace, including its spans, send a GET request to /api/v2/workspaces/{workspace_id}/indexes/{pipeline_index_id}/traces/{run_id}.

    In the UI, open the index and click the Traces tab.

Keep the following in mind:

  • capture_trace defaults to false. If you omit it, the file is reindexed without a trace.
  • The trace covers the whole batch the file is indexed in, so when the queue is busy, it can also show other files. Each file in the trace has its own capture_trace value, so you can tell which file you requested.
  • Only the single-file reindex request can capture a trace. File uploads, dataset imports, upload sessions, and reindexing files by status never capture one.

For the full request and response details, see the Schedule Single File For Indexing API reference.