# Retrieve a prompt template

div
strong
🔨 In Development
 — This section is still being developed and may change.


Fetches a specific prompt template by its unique identifier, including full details and variable definitions.

Use this endpoint to get the complete definition of a prompt template for use in model response requests or for template management.

#### Path Parameters

**`prompt_id`** string *required*

The unique identifier of the prompt template to retrieve.

#### Query Parameters

**`organizationId`** string *required*

The unique identifier of the organization that owns the prompt template. Ensures access control and proper scoping.

**`includeUsage`** boolean *optional* · Defaults to `false`

When `true`, includes usage statistics and recent usage history for the prompt template.

#### Response

Returns the complete prompt template object with all properties:

**`id`** string

The unique identifier of the prompt template.

**`object`** string

Always set to `"prompt"`.

**`name`** string

The human-readable name of the prompt template.

**`description`** string

Detailed description of the template's purpose and usage.

**`content`** string

The full prompt template content with variable placeholders (e.g., `{{variable_name}}`).

**`variables`** object

Complete variable definitions including types, descriptions, defaults, and validation rules.

**`tags`** array

Array of tags assigned to the template for categorization.

**`isPublic`** boolean

Whether the template is publicly accessible.

**`metadata`** object

Custom metadata attached to the template.

**`createdAt`** integer

Unix timestamp when the template was created.

**`updatedAt`** integer

Unix timestamp of the last modification.

**`version`** string

The current version identifier of the template.

**`usage`** object *optional*

Usage statistics (only included when `includeUsage=true`):

- `totalCalls` integer - Total number of API calls using this template
- `lastUsedAt` integer - Timestamp of most recent usage
- `averageResponseTime` number - Average response time in seconds
- `recentUsages` array - Last 5 usage records with timestamps and models used


## Returns

A [PromptResponse](#promptresponse) object containing the API response data.

Basic retrieval

```bash
curl "https://api.freddy.aitronos.com/v1/prompts/prompt_abc123?organizationId=org_abc123" \
-H "Authorization: Bearer $FREDDY_API_KEY"
```


```python
import requests
import os

response = requests.get(
  f"https://api.freddy.aitronos.com/v1/prompts/prompt_abc123",
  headers={
      "Authorization": f"Bearer {os.environ['FREDDY_API_KEY']}"
  },
  params={
      "organizationId": "org_abc123"
  }
)

prompt = response.json()
print(f"Template: {prompt['name']}")
print(f"Content: {prompt['content'][:100]}...")
```


```javascript
const promptId = 'prompt_abc123';
const response = await fetch(`https://api.freddy.aitronos.com/v1/prompts/${promptId}?organizationId=org_abc123`, {
headers: {
  'Authorization': `Bearer ${process.env.FREDDY_API_KEY}`
}
});

const prompt = await response.json();
console.log(`Template: ${prompt.name}`);
console.log(`Content: ${prompt.content.substring(0, 100)}...`);
```

With usage statistics

```bash
curl "https://api.freddy.aitronos.com/v1/prompts/prompt_abc123?organizationId=org_abc123&includeUsage=true" \
-H "Authorization: Bearer $FREDDY_API_KEY"
```


```python
response = requests.get(
  f"https://api.freddy.aitronos.com/v1/prompts/prompt_abc123",
  headers={"Authorization": f"Bearer {api_key}"},
  params={
      "organizationId": "org_abc123",
      "includeUsage": True
  }
)

prompt = response.json()
print(f"Total calls: {prompt.get('usage', {}).get('totalCalls', 0)}")
print(f"Last used: {prompt.get('usage', {}).get('lastUsedAt')}")
```


```javascript
const response = await fetch('https://api.freddy.aitronos.com/v1/prompts/prompt_abc123?organizationId=org_abc123&includeUsage=true', {
headers: {
  'Authorization': `Bearer ${apiKey}`
}
});

const prompt = await response.json();
const usage = prompt.usage || {};
console.log(`Total calls: ${usage.totalCalls || 0}`);
console.log(`Last used: ${usage.lastUsedAt}`);
```

Error handling

```bash
# 404 - Prompt not found
curl "https://api.freddy.aitronos.com/v1/prompts/nonexistent_prompt?organizationId=org_abc123" \
-H "Authorization: Bearer $FREDDY_API_KEY"
```


```json
{
"error": {
  "message": "Prompt template not found",
  "type": "not_found_error",
  "code": "prompt_not_found",
  "param": "prompt_id"
}
}
```


```python
try:
  response = requests.get(
      f"https://api.freddy.aitronos.com/v1/prompts/nonexistent_prompt",
      headers={"Authorization": f"Bearer {api_key}"},
      params={"organizationId": "org_abc123"}
  )
  prompt = response.json()
except requests.exceptions.HTTPError as e:
  if response.status_code == 404:
      print("Prompt not found")
  else:
      print(f"Error: {response.json()}")
```


```javascript
try {
const response = await fetch('https://api.freddy.aitronos.com/v1/prompts/nonexistent_prompt?organizationId=org_abc123', {
  headers: {
    'Authorization': `Bearer ${apiKey}`
  }
});

if (!response.ok) {
  const error = await response.json();
  if (response.status === 404) {
    console.log('Prompt not found');
  } else {
    console.error('Error:', error);
  }
  return;
}

const prompt = await response.json();
console.log(prompt);
} catch (error) {
console.error('Network error:', error);
}
```

#### Example Response


```json
{
  "id": "prompt_abc123",
  "object": "prompt",
  "name": "Code Review Assistant",
  "description": "Reviews code pull requests and provides improvement suggestions",
  "content": "You are an expert code reviewer. Analyze the following code and provide constructive feedback focusing on {{focus_areas}}. Code to review:\n\n{{code}}\n\nLanguage: {{language}}",
  "variables": {
    "focus_areas": {
      "type": "string",
      "description": "Areas to focus the review on (e.g., security, performance, readability)",
      "required": false,
      "default": "best practices"
    },
    "code": {
      "type": "string",
      "description": "The code to review",
      "required": true
    },
    "language": {
      "type": "string",
      "description": "Programming language of the code",
      "required": true,
      "enum": ["javascript", "python", "java", "go", "rust", "typescript"]
    }
  },
  "tags": ["code-review", "development", "quality"],
  "isPublic": false,
  "metadata": {
    "team": "engineering",
    "category": "code-quality"
  },
  "createdAt": 1735689600,
  "updatedAt": 1735689600,
  "version": "1.0.0",
  "usage": {
    "totalCalls": 45,
    "lastUsedAt": 1736208000,
    "averageResponseTime": 2.3,
    "recentUsages": [
      {
        "timestamp": 1736208000,
        "model": "gpt-4o",
        "organizationId": "org_abc123"
      }
    ]
  }
}
```

## Related Resources

- [Create Prompt](/docs/api-reference/prompts/create)
- [List Prompts](/docs/api-reference/prompts/list)
- [Update Prompt](/docs/api-reference/prompts/update)
- [Delete Prompt](/docs/api-reference/prompts/delete)
- [Using Prompt Templates](/docs/api-reference/responses/create#prompt)