> ## Documentation Index
> Fetch the complete documentation index at: https://kosli-reference-docs-v2-30-1.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# kosli list trails

> List Trails of an org.

## Synopsis

```shell theme={null}
kosli list trails [flags]
```

List Trails of an org.The list can be filtered by flow, flow tag and artifact fingerprint. When multiple filters are provided, only trails matching all specified criteria are returned. The results are paginated and ordered from latest to oldest.

## Flags

| Flag                         | Description                                                                                 |
| :--------------------------- | :------------------------------------------------------------------------------------------ |
| `-F`, `--fingerprint` string | \[optional] The SHA256 fingerprint of the artifact to filter trails by.                     |
| `-f`, `--flow` string        | \[optional] The Kosli flow name.                                                            |
| `-t`, `--flow-tag` string    | \[optional] A key=value flow tag to filter trails by.                                       |
| `-h`, `--help`               | help for trails                                                                             |
| `-o`, `--output` string      | \[defaulted] The format of the output. Valid formats are: \[table, json]. (default "table") |
| `--page` int                 | \[defaulted] The page number of a response. (default 1)                                     |
| `-n`, `--page-limit` int     | \[defaulted] The number of elements per page. (default 20)                                  |

## Flags inherited from parent commands

| Flag                          | Description                                                                                                                                             |
| :---------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `-a`, `--api-token` string    | The Kosli API token.                                                                                                                                    |
| `-c`, `--config-file` string  | \[optional] The Kosli config file path. (default "kosli")                                                                                               |
| `--debug`                     | \[optional] Print debug logs to stdout.                                                                                                                 |
| `-H`, `--host` string         | \[defaulted] The Kosli endpoint. (default "[https://app.kosli.com](https://app.kosli.com)")                                                             |
| `--http-proxy` string         | \[optional] The HTTP proxy URL including protocol and port number. e.g. `http://proxy-server-ip:proxy-port`                                             |
| `-r`, `--max-api-retries` int | \[defaulted] How many times should API calls be retried when the API host is not reachable. (default 3)                                                 |
| `--org` string                | The Kosli organization.                                                                                                                                 |
| `-q`, `--quiet`               | \[optional] Suppress non-critical warning messages. Errors and normal output are not affected. If both `--quiet` and `--debug` are set, `--debug` wins. |

## Examples Use Cases

These examples all assume that the flags  `--api-token`, `--org`, `--host`, (and `--flow`, `--trail` when required), are [set/provided](/getting_started/install/#assigning-flags-via-environment-variables).

<AccordionGroup>
  <Accordion title="get a paginated list of trails for a flow">
    ```shell theme={null}
    kosli list trails 

    ```
  </Accordion>

  <Accordion title="list the most recent 30 trails for a flow">
    ```shell theme={null}
    kosli list trails 
    	--page-limit 30 

    ```
  </Accordion>

  <Accordion title="show the second page of trails for a flow">
    ```shell theme={null}
    kosli list trails 
    	--page-limit 30 
    	--page 2 

    ```
  </Accordion>

  <Accordion title="get a paginated list of trails for a flow (in JSON)">
    ```shell theme={null}
    kosli list trails 
    	--output json

    ```
  </Accordion>

  <Accordion title="get a paginated list of trails across all flows that contain an artifact with the provided fingerprint (in JSON)">
    ```shell theme={null}
    kosli list trails 
    	--fingerprint yourArtifactFingerprint 
    	--output json

    	# get a paginated list of trails across all flows tagged with the provided key-value pair:
    kosli list trails 
    	--flow-tag team=backend 
    ```
  </Accordion>
</AccordionGroup>