---
title: "Show an output to the user"
method: POST
path: "/v1/tools/show_output"
---

# Show an output to the user

`POST /v1/tools/show_output`

## Request

- Base URL: `https://api.ploti.ai`
- URL: `https://api.ploti.ai/v1/tools/show_output`
- Auth: HTTP bearer

Display a checkpoint's entities, a materialized table's rows, a saved query's live results, or a saved filter's map. Returns viewUrl — the user-facing Ploti link for the artifact; create calls do not return one. Each call also creates a view-only link that needs no sign-in and lasts 7 days. Also returns a compact row preview as text and, in supported clients, an interactive panel that loads the full artifact separately. Use limit, offset, and columns to page or narrow the preview; expression columns from a checkpoint's table_config render in Ploti but are omitted from the preview. Use this tool to hand a result to the user rather than pasting rows into your reply. An answer about places is handed over as one filter (tools.filters.create) holding the result and the layer it rests on, and its viewUrl goes in your reply.

## Request body

- object
  - `sessionId` string, required: The id start_session returned. Lost it? get_session without an id lists this workspace's open sessions.
  - `kind` 'checkpoint' | 'table' | 'query' | 'filter', required: The kind of output the id names, as list_outputs groups it: a checkpoint's entities, a table's rows, a saved query's live results, or a filter's map.
  - `id` string, required: Checkpoint, materialized table, saved query, or filter id.
  - `limit` integer: Rows in the text preview; 10 when left out. The interactive panel loads the full output on its own.
  - `offset` integer: The row the preview starts at, for paging through it; the first row when left out.
  - `columns` string[]: Columns to show in the preview, by name; left out, a checkpoint shows its table_config columns and a table or query its own.

## Response `200`

What the tool returned: its text, any images, and structured data.

- object
  - `text` string, required
  - `images` object[], required
    - `mimeType` string
    - `data` string, byte
  - `data` unknown

## Other responses

- `400`: invalid_input: the arguments do not fit the tool's input schema.
- `403`: insufficient_scope: the credential may not use this tool.
- `404`: not_found: there is no such tool.
- `413`: payload_too_large: the body is over 256 KB (2 MB for /v1/tools).
- `415`: unsupported_media_type: a body was sent without Content-Type: application/json.
- `422`: tool_error: the tool refused or failed; error.message says why.
- `429`: rate_limited: this credential is over its rate. Retry after the Retry-After header's seconds.
- `500`: internal: Ploti failed. Retry; if it keeps happening, contact support.

---

[API](https://skmtc.dev/ploti/apis/ploti-api.md) · [All operations](https://skmtc.dev/ploti/apis/ploti-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ploti/apis/ploti-api/revisions/8c2c91c72d52?raw)