> ## Documentation Index
> Fetch the complete documentation index at: https://developer.watson-orchestrate.ibm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Using traces with ADK CLI

Use the watsonx Orchestrate ADK CLI to get traces from your active environment and export their spans.

<Warning>
  **AWS Environment Limitation: June 11-25, 2026**

  ADK trace commands do not return new incoming traces between June 11th and June 25th in AWS environments. Call the Trace endpoints directly during this period.

  For direct API access, see:

  * [Observability API Migration Guide: v1 to AgentOps v3](https://developer.ibm.com/apis/catalog/watsonorchestrate--custom-assistants/Observability+API+Migration+Guide:+v1+to+AgentOps+v3)
  * [Observability](https://developer.ibm.com/apis/catalog/watsonorchestrate--custom-assistants/api/API--watsonorchestrate--agentops-and-analytics#getTraces)
</Warning>

## Searching traces

Use filters to search for traces.

You identify trace IDs by setting criteria such as time range, service names, agent identifiers or names, user identifiers, session identifiers, or span count.

```bash BASH theme={null}
orchestrate observability traces search --start-time <start date and time for search> --end-time <end date and time for search>
```

<Expandable title="command flags">
  <ResponseField name="--start-time" type="datetime" required>
    A start time for the results.
    This flag cannot be used with `--last` flag.
  </ResponseField>

  <ResponseField name="--end-time" type="datetime" required>
    An end time for the results.
    This flag cannot be used with `--last` flag.
  </ResponseField>

  <ResponseField name="--service-name / -s" type="string">
    A service name to filter results. Can be specified multiple times.
  </ResponseField>

  <ResponseField name="--agent-id / -i" type="string">
    An agent ID to filter results. Can be specified multiple times.
  </ResponseField>

  <ResponseField name="--agent-name / -a" type="string">
    An agent name to filter results. Can be specified multiple times.
  </ResponseField>

  <ResponseField name="--user-id / -u" type="string">
    A user ID to filter results. Can be specified multiple times.
  </ResponseField>

  <ResponseField name="--session-id" type="string">
    A session ID to filter results. Can be specified multiple times.
  </ResponseField>

  <ResponseField name="--min-spans" type="int">
    A minimum span count for a trace.
  </ResponseField>

  <ResponseField name="--max-spans" type="int">
    A maximum span count for a trace.
  </ResponseField>

  <ResponseField name="--sort-field" type="SortField">
    A field used for sorting results.
  </ResponseField>

  <ResponseField name="--sort-direction" type="SortDirection">
    A sort direction for the results.
  </ResponseField>

  <ResponseField name="--limit / -l" type="int">
    A limit on the number of traces returned. Configure a value from 1 to 1000.
  </ResponseField>

  <ResponseField name="--last" type="string">
    The shorthand for setting a relative time window that ends now. You can enter:

    * Minutes. For example: `30m` / `30 minutes`
    * Hours. For example: `3h` / `3 hours`
    * Days. For example: `10d` / `10 days`
      This flag cannot be used with `--start-time` or `--end-time` flags.
  </ResponseField>
</Expandable>

After you identify the trace IDs, run [`orchestrate observability traces export`](#exporting-traces-spans) to export the full trace data.

## Exporting traces spans

Export spans from the watsonx Orchestrate observability platform.

This command fetches all spans for a specific trace ID and sends them to a file or standard output in JSON format. The JSON output follows the OpenTelemetry specification.

```bash BASH theme={null}
orchestrate observability traces export --trace-id <trace ID>
```

<Expandable title="command flags">
  <ResponseField name="--trace-id / -t" type="string" required>
    A 32‑character hexadecimal trace ID to export.
  </ResponseField>

  <ResponseField name="--output / -o" type="string">
    A file path for the command output. When omitted, output is displayed in the CLI.

    <Note>
      **Note**

      The output file must be in JSON format. When a different file type is provided, a warning is shown.
    </Note>
  </ResponseField>

  <ResponseField name="--pretty | --no-pretty" type="bool">
    Indented JSON output for easier readability. This flag is used only with the `--output` / `-o` flag. Default is `--pretty`.
  </ResponseField>
</Expandable>