---
title: "Get instruction"
method: GET
path: "/v2/instructions/{instruction_id}"
tags: ["Instructions"]
---

# Get instruction

`GET /v2/instructions/{instruction_id}`

Returns the full definition of an instruction, including its template, metadata, enabled status, and version. Instruction templates may contain Velocity expressions that reference tools and metadata. If no version is specified, the platform returns the latest version.

## Path parameters

- `instruction_id` string, required — The unique identifier for an instruction.

## Query parameters

- `version` integer

## Headers

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

## Response `200`

The requested instruction details.

- Instruction — An initial instruction that provides guidance to the agent before user messages.
  - `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.

## Other responses

- `403` — Permissions do not allow accessing this instruction.
- `404` — Instruction not found.

---

[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/e85040b266cc/schema)