---
title: "List instructions"
method: GET
path: "/v2/instructions"
tags: ["Instructions"]
---

# List instructions

`GET /v2/instructions`

Lists all instructions available to the authenticated user, with optional filtering and pagination. The response includes high-level information about each instruction: the name, status, and version details.

## Query parameters

- `filter` string
- `type` 'initial'
- `enabled` boolean
- `limit` integer
- `page_key` string

## Headers

- `Request-Timeout` integer
- `Request-Timeout-Millis` integer

## Response `200`

List of available instructions.

- ListInstructionsResponse — Response containing a list of instructions.
  - `instructions` Instruction[], required — List of instructions.
    - `id` string, required — The unique identifier for an instruction.
    - `type` string, required — The type of instruction.
    - `name` string, required — The human-readable name of an instruction.
    - `description` string — A detailed description of what this instruction does.
    - `template_type` 'velocity' | 'text', required — The templating engine used to render the instruction's template. - `velocity`: render the template with the Velocity engine, substituting agent, session, and tool variables. - `text`: use the template verbatim as plain text, with no variable substitution.
    - `template` string, required — The instruction template content. How it is rendered depends on the sibling `template_type`. When `template_type` is `text`, the content is used verbatim as the instruction and no variables are substituted. When `template_type` is `velocity`, the content is rendered with the Velocity engine and the following variables are available: - `$agent.name` - Agent name - `$agent.key` - Agent key - `$agent.metadata` - Agent metadata map - `$session.key` - Session key - `$session.metadata` - Session metadata map (includes user-provided context from test/runtime) - `$currentDate` - Current date/time in ISO 8601 format (e.g., "2025-10-24T15:30:45Z") - `$tools` - List of tool maps, each with `name` and `description` fields Example: `You are a helpful customer support agent. Agent: $agent.name. Today is $currentDate. Available tools: #foreach($tool in $tools)${tool.name}#if($foreach.hasNext), #end#end`
    - `version` integer, required — The version identifier for this instruction. The version increments automatically when the instruction is updated.
    - `metadata` object — Arbitrary metadata associated with the instruction.
    - `enabled` boolean, required — Whether the instruction is currently enabled and available for use.
    - `created_at` string, date-time — Timestamp when the instruction was created.
    - `updated_at` string, date-time — Timestamp when the instruction was last updated.
  - `metadata` ListMetadata, required — The standard metadata in the response of a list operation.
    - `page_key` string — The page key for the next page of results. Pass it as a query parameter to request the next page.

## Other responses

- `403` — Permissions do not allow listing instructions.

---

[API](https://skmtc.net/vectara/apis/vectara-rest-api-v2.md) · [All operations](https://skmtc.net/vectara/apis/vectara-rest-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/vectara/vectara-rest-api-v2/versions/fca567a46b3a/schema)