> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trellis.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# List Saved Queries

> Retrieve all saved queries for your organization

Saved queries allow your organization to store reusable, parameterized SQL queries paired with a natural language prompt. They can be invoked directly in chat messages to execute deterministic SQL without going through the AI agent.

<ParamField header="Authorization" type="string" required>
  Bearer token obtained from the authenticate endpoint.
</ParamField>

## Response

<ResponseField name="queries" type="array" required>
  List of saved queries.

  <Expandable title="Query object">
    <ResponseField name="id" type="string" required>
      Unique identifier for the saved query.
    </ResponseField>

    <ResponseField name="organization_id" type="string" required>
      Organization the query belongs to.
    </ResponseField>

    <ResponseField name="title" type="string" required>
      Display title for the query.
    </ResponseField>

    <ResponseField name="description" type="string">
      Optional human-readable description of what the query does.
    </ResponseField>

    <ResponseField name="prompt" type="string" required>
      The natural language instruction passed to the AI agent when this query is invoked.
    </ResponseField>

    <ResponseField name="sql" type="string">
      The SQL executed when this query runs, or `null` for prompt-only queries. May contain `{{param_name}}` placeholders for runtime substitution.
    </ResponseField>

    <ResponseField name="keywords" type="string[]">
      Optional list of keywords used for automatic semantic matching. When a chat message's content matches these terms, this query may be surfaced automatically.
    </ResponseField>

    <ResponseField name="parameters" type="string[]">
      Names of all `{{param_name}}` placeholders found in `sql`, auto-extracted by the server. Supply values for these when invoking the query via the [Send Message](/api-reference/chats/send-message) endpoint.
    </ResponseField>

    <ResponseField name="last_updated_by" type="string" required>
      Member ID of the user who last modified this query.
    </ResponseField>

    <ResponseField name="last_updated_by_name" type="string">
      Display name of the user who last modified this query.
    </ResponseField>

    <ResponseField name="created_at" type="string" required>
      ISO 8601 timestamp when the query was created.
    </ResponseField>

    <ResponseField name="updated_at" type="string" required>
      ISO 8601 timestamp when the query was last modified.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X GET https://api.trellis.sh/v1/queries \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  response = requests.get(
      "https://api.trellis.sh/v1/queries",
      headers={"Authorization": "Bearer YOUR_TOKEN"}
  )
  queries = response.json()["queries"]
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch("https://api.trellis.sh/v1/queries", {
    headers: { Authorization: "Bearer YOUR_TOKEN" },
  });
  const { queries } = await response.json();
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "queries": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "organization_id": "org_abc123",
        "title": "Monthly Revenue",
        "description": "Total revenue grouped by month for a given year",
        "prompt": "Show me total revenue by month for {{year}}",
        "sql": "SELECT DATE_TRUNC('month', created_at) AS month, SUM(amount) AS revenue FROM orders WHERE EXTRACT(year FROM created_at) = {{year}} GROUP BY 1 ORDER BY 1",
        "keywords": ["revenue", "monthly", "sales"],
        "parameters": ["year"],
        "last_updated_by": "member_xyz789",
        "last_updated_by_name": "John Doe",
        "created_at": "2025-11-01T10:00:00Z",
        "updated_at": "2025-12-01T15:30:00Z"
      }
    ]
  }
  ```
</ResponseExample>