# List prompts

> Returns Prompt receipts newest first, ordered by created_at then ID.

See [prompt workflows](https://revise.io/developer/docs/revise-api/prompts) for integration guidance.

## TypeScript

```ts
import { ReviseClient } from "@reviseio/api";

const revise = new ReviseClient({ apiKey: process.env.REVISE_API_KEY! });
const result = await revise.prompts.list({ limit: 20, metadata: { customer: "acme" } });
```

`GET https://revise.io/api/v1/prompts`

Returns Prompt receipts newest first, ordered by created_at then ID. Pass next_cursor with the same filters for the next page; null means the end. Cursors belong to the authenticated account. Filters combine with AND. Status is current, not a frozen snapshot. Metadata filters stop matching after content expiry or deletion. Unknown or repeated query parameters return 400.

## Authorization

`Authorization: Bearer <key>` with an API key from https://revise.io/console/api-keys.

## Query parameters

- `limit` (integer): min 1. max 100
- `cursor` (string): The next_cursor returned by the previous page.
- `status` (string): one of "queued", "running", "paused", "succeeded", "failed", "cancelled"
- `conversation_id` (string): Exact conv_ ID.
- `api_key_id` (string): Exact key_ ID of the submitting key. Older unattributed prompts do not match.
- `created_after` (string<date-time>): Inclusive lower creation-time bound (RFC3339 with timezone).
- `created_before` (string<date-time>): Exclusive upper creation-time bound (RFC3339 with timezone).
- `metadata` (object): Exact AND matches, e.g. metadata[customer]=Acme. Keys up to 64 bytes; values up to 512 bytes.

## Responses

### 200 `object`

A page of prompts

- `data` (array<Prompt>, required): max items 100
  - `id` (string, required)
  - `conversation_id` (string, required)
  - `previous_prompt_id` (string | null, required)
  - `status` (string, required): one of "queued", "running", "paused", "succeeded", "failed", "cancelled"
  - `created_at` (string<date-time>, required)
  - `completed_at` (string<date-time> | null, required)
  - `conversation_expires_at` (string<date-time> | null, required)
  - `message` (Message | null, required)
  - `continuation` (Continuation, required)
    - `reasoning_state` (string, required): one of "new", "reused", "reset", "compacted", "unavailable"
    - `history_compacted` (boolean | null, required)
    - `reason` (string)
  - `comments` (array<NativeComment>): Flat native comment records; replies use parentId. Omitted when disabled by response_options or when content is unavailable.
    - `id` (string, required)
    - `author` (string, required)
    - `initials` (string)
    - `authorId` (string)
    - `authorImageUrl` (string)
    - `createdAt` (string<date-time>, required)
    - `bodyMd` (string, required): Comment text in Markdown.
    - `parentId` (string): Parent comment ID for a reply; absent for a root comment.
    - `agentRequestId` (string)
    - `agentConversationId` (string)
    - `agentName` (string)
    - `agentModel` (string)
    - `suggestionId` (string)
    - `anchorBlockId` (string)
    - `agentTriggerIds` (array<string>)
    - `relatedSuggestionIds` (array<string>)
    - `resolved` (boolean)
    - `authorType` (string): one of "human", "ai"
    - `importedId` (integer)
    - `citations` (array<Citation>)
      - `id` (string, required)
      - `url` (string, required)
      - `title` (string, required)
      - `startIndex` (integer)
      - `endIndex` (integer)
    - `mentions` (array<object>)
      - `id` (string, required)
      - `type` (string, required): one of "user", "agent"
      - `label` (string, required)
      - `start` (integer, required)
      - `end` (integer, required)
      - `email` (string)
  - `changes` (array<NativeTrackedChange>): Pending native tracked changes. Replacements can appear as linked insertion/deletion entries. Omitted when disabled by response_options or when content is unavailable.
    - `id` (string, required)
    - `kind` (string, required): one of "insert", "delete", "format", "move"
    - `blockIds` (array<string>, required)
    - `commentThreadId` (string)
    - `author` (string, required)
    - `agentModel` (string)
    - `description` (string)
    - `insertedText` (string)
    - `deletedText` (string)
    - `authorType` (string, required): one of "human", "ai"
    - `createdAt` (number): Unix time in milliseconds, when recorded.
    - `moveSourceBlockIds` (array<string>)
    - `moveDestinationBlockIds` (array<string>)
  - `artifacts` (array<Artifact>, required)
    - `id` (string, required)
    - `prompt_id` (string)
    - `conversion_id` (string)
    - `format` (string, required): one of "docx", "pdf", "md", "html", "txt"
    - `filename` (string, required): Original plaintext filename, even when encrypted. Encrypted downloads append .jwe.
    - `content_type` (string, required): Original plaintext MIME type. Encrypted downloads use application/jose.
    - `variant` (string, required): one of "tracked_changes", "clean", "converted"
    - `sha256` (string, required): SHA-256 of the exact downloadable bytes (ciphertext for encrypted artifacts).
    - `bytes` (integer, required): Size of the downloadable bytes, including JWE encoding overhead when encrypted.
    - `download_url` (string, required): Account-authenticated API path. The endpoint may redirect to signed storage; never forward bearer credentials to storage.
    - `input_eligible` (boolean, required): True only for an unexpired, undeleted, unencrypted prompt artifact. Conversion artifacts are not directly reusable; download and upload them first.
    - `expires_at` (string | null, required)
    - `encryption` (ArtifactEncryption)
      - `format` (string, required): one of "jwe"
      - `alg` (string, required): one of "RSA-OAEP-256"
      - `enc` (string, required): one of "A256GCM"
      - `key_id` (string, required): Base64url SHA-256 JWK thumbprint of the recipient public key (RFC7638).
    - `deleted_at` (string | null, required)
  - `usage` (Usage | null, required)
  - `metadata` (Metadata, required): Up to 16 string values for application attribution. Keys are 1–64 UTF-8 bytes; values at most 512 UTF-8 bytes. Metadata is deleted with request content; persist your own job mapping for long-term attribution.. example {"customer":"acme","environment":"production"}
  - `inference` (object, required)
    - `provider` (string, required): one of "openai", "anthropic", "xai", "gemini"
    - `model` (string, required)
    - `billing` (string, required): The billing that applied at admission; fixed for the life of the request even if account keys change later.. one of "revise", "provider"
  - `limits` (object, required)
    - `max_platform_cost_usd` (string): example "0.050000000"
    - `max_inference_cost_usd` (string): example "0.050000000"
    - `max_seconds` (integer, required)
  - `error` (object | null, required)
  - `api_key_id` (string | null, required): Non-secret ID of the key that originally submitted this prompt; null when not recorded. Idempotent retries preserve the original key.
  - `output_encrypted` (boolean, required): True disables continuation and reuse. Artifacts are encrypted for the supplied public key.
  - `content_expires_at` (string | null, required): 24 hours after terminal completion. Result content and new continuation become unavailable at this deadline.
  - `content_deleted_at` (string | null, required)
  - `retention` (RetentionOptions)
    - `delete_after_webhook_id` (string, required): Account-owned endpoint subscribed to prompt.completed or conversion.completed, matching the request kind. Its successful acknowledgement deletes request content and ephemeral source. Download everything before returning 2xx.
  - `incomplete` (boolean, required): True when the request returned a partial result.
  - `stop_reason` (string): Limit that ended further agent work. The current result is returned; successful partial results incur the base fee even without inference, plus actual billable usage.. one of "spending_limit", "time_limit"
- `next_cursor` (string | null, required)

### default `Error`

Error

- `error` (object, required)
  - `code` (string, required)
  - `message` (string, required)
  - `details` (object)
