> This page is for version v5.0 (default).
> For other versions, use one of these documentation indexes:
> - v5.0 (default): https://humanloop.com/docs/v5/llms.txt
> - v4.0: https://humanloop.com/docs/v4/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://humanloop.com/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://humanloop.com/docs/_mcp/server.

> Learn how to call your Prompts that are managed on Humanloop.

This guide will show you how to call your Prompts through the API, enabling you to generate responses from the large language model while versioning your Prompts.

You can call an existing Prompt on Humanloop, or you can call a Prompt you're managing in code. These two use-cases are demonstrated below.

### Prerequisites

#### Install and initialize the SDK

First you need to install and initialize the SDK. If you have already done this, skip to the next section.

Open up your terminal and follow these steps:

1. Install the Humanloop SDK:

```python
pip install humanloop
```

```typescript
npm install humanloop
```

2. Initialize the SDK with your Humanloop API key (you can get it from the [Organization Settings page](https://app.humanloop.com/account/api-keys)).

```python
from humanloop import Humanloop
humanloop = Humanloop(api_key="<YOUR HUMANLOOP KEY>")

# Check that the authentication was successful
print(humanloop.prompts.list())
```

```typescript
import { HumanloopClient, Humanloop } from "humanloop";

const humanloop = new HumanloopClient({ apiKey: "YOUR_API_KEY" });

// Check that the authentication was successful
console.log(await humanloop.prompts.list());
```

## Call an existing Prompt

If you don't have Prompt already on Humanloop, please follow our [Prompt creation](/docs/development/guides/create-prompt) guide first.

### Get the Prompt ID

In Humanloop, navigate to the Prompt and copy the Prompt ID by clicking Prompt name in the top bar, and copying from the popover.

![](/docs/_fern-img/d9f35e326581c5a1cb66ecb5bfcc820d905c1f554cd5eaf762431b8520d30893.webp)

### Call the Prompt by ID

Now you can use the SDK to generate completions and log the results to your Prompt:

This can be done by using the [Prompt Call](/docs/api/prompts/call) method in the SDK.

### Request

POST [https://api.humanloop.com/v5/prompts/call](https://api.humanloop.com/v5/prompts/call)

**`By ID`**

```curl By ID
curl -X POST "https://api.humanloop.com/v5/prompts/call?version_id=prv_Wu6zx1lAWJRqOyL8nWuZk" \
     -H "X-API-KEY: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "path": "persona",
  "messages": [
    {
      "role": "user",
      "content": "What really happened at Roswell?"
    }
  ],
  "inputs": {
    "person": "Trump"
  }
}'
```

**`By ID`**

```python By ID
import requests

url = "https://api.humanloop.com/v5/prompts/call"

querystring = {"version_id":"prv_Wu6zx1lAWJRqOyL8nWuZk"}

payload = {
    "path": "persona",
    "messages": [
        {
            "role": "user",
            "content": "What really happened at Roswell?"
        }
    ],
    "inputs": { "person": "Trump" }
}
headers = {
    "X-API-KEY": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers, params=querystring)

print(response.json())
```

**`By ID`**

```typescript By ID
import { HumanloopClient } from "humanloop";

const client = new HumanloopClient({ apiKey: "YOUR_API_KEY" });
await client.prompts.call({
    versionId: "prv_Wu6zx1lAWJRqOyL8nWuZk",
    path: "persona",
    messages: [{
            role: "user",
            content: "What really happened at Roswell?"
        }],
    inputs: {
        "person": "Trump"
    }
});

```

**`By ID`**

```go By ID
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.humanloop.com/v5/prompts/call?version_id=prv_Wu6zx1lAWJRqOyL8nWuZk"

	payload := strings.NewReader("{\n  \"path\": \"persona\",\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"What really happened at Roswell?\"\n    }\n  ],\n  \"inputs\": {\n    \"person\": \"Trump\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-KEY", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

**`By ID`**

```ruby By ID
require 'uri'
require 'net/http'

url = URI("https://api.humanloop.com/v5/prompts/call?version_id=prv_Wu6zx1lAWJRqOyL8nWuZk")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"path\": \"persona\",\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"What really happened at Roswell?\"\n    }\n  ],\n  \"inputs\": {\n    \"person\": \"Trump\"\n  }\n}"

response = http.request(request)
puts response.read_body
```

**`By ID`**

```java By ID
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.humanloop.com/v5/prompts/call?version_id=prv_Wu6zx1lAWJRqOyL8nWuZk")
  .header("X-API-KEY", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"path\": \"persona\",\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"What really happened at Roswell?\"\n    }\n  ],\n  \"inputs\": {\n    \"person\": \"Trump\"\n  }\n}")
  .asString();
```

**`By ID`**

```php By ID
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.humanloop.com/v5/prompts/call?version_id=prv_Wu6zx1lAWJRqOyL8nWuZk', [
  'body' => '{
  "path": "persona",
  "messages": [
    {
      "role": "user",
      "content": "What really happened at Roswell?"
    }
  ],
  "inputs": {
    "person": "Trump"
  }
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'X-API-KEY' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

**`By ID`**

```csharp By ID
using RestSharp;

var client = new RestClient("https://api.humanloop.com/v5/prompts/call?version_id=prv_Wu6zx1lAWJRqOyL8nWuZk");
var request = new RestRequest(Method.POST);
request.AddHeader("X-API-KEY", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"path\": \"persona\",\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"What really happened at Roswell?\"\n    }\n  ],\n  \"inputs\": {\n    \"person\": \"Trump\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

**`By ID`**

```swift By ID
import Foundation

let headers = [
  "X-API-KEY": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "path": "persona",
  "messages": [
    [
      "role": "user",
      "content": "What really happened at Roswell?"
    ]
  ],
  "inputs": ["person": "Trump"]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.humanloop.com/v5/prompts/call?version_id=prv_Wu6zx1lAWJRqOyL8nWuZk")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Response (200)

```json
{
  "prompt": {
    "path": "persona",
    "id": "pr_3usCu3dAkgrXTlufrvPs7",
    "model": "gpt-4",
    "name": "persona",
    "version_id": "prv_Wu6zx1lAWJRqOyL8nWuZk",
    "created_at": "2024-05-01T12:00:00Z",
    "updated_at": "2024-05-01T12:00:00Z",
    "last_used_at": "2024-05-01T12:00:00Z",
    "version_logs_count": 1,
    "total_logs_count": 1,
    "inputs": [
      {
        "name": "person"
      }
    ],
    "template": [
      {
        "role": "system",
        "content": "You are {{person}}. Answer any questions as this person. Do not break character."
      }
    ],
    "provider": "openai",
    "type": "prompt"
  },
  "id": "data_fIfEb1SoKZooqeFbi9IFs",
  "logs": [
    {
      "index": 0,
      "output": "Well, let me tell you, there are a lot of stories about Roswell, and I hear them all the time.\n People love to talk about Roswell. So many theories, so many ideas. Some folks believe it was a weather balloon, others say it was something out of this world. Believe me, there's plenty that we don't know. Very interesting to look into, but the truth, well, it might still be out there. Could be a great story, who knows? But what I do know, folks, is that we have to keep our eyes open and always be on the lookout for the truth!",
      "created_at": "2024-05-01T12:00:00Z",
      "output_message": {
        "role": "assistant",
        "content": "Well, let me tell you, there are a lot of stories about Roswell, and I hear them all the time.\n People love to talk about Roswell. So many theories, so many ideas. Some folks believe it was a weather balloon, others say it was something out of this world. Believe me, there's plenty that we don't know. Very interesting to look into, but the truth, well, it might still be out there. Could be a great story, who knows? But what I do know, folks, is that we have to keep our eyes open and always be on the lookout for the truth!"
      },
      "prompt_tokens": 34,
      "output_tokens": 125,
      "finish_reason": "stop"
    }
  ]
}
```

## Call a Prompt defined in code

You can also manage your Prompts in code. Pass the `prompt` details within your API call to generate responses with
the specified parameters.

### Request

POST [https://api.humanloop.com/v5/prompts/call](https://api.humanloop.com/v5/prompts/call)

**`Supplying Prompt`**

```curl Supplying Prompt
curl -X POST https://api.humanloop.com/v5/prompts/call \
     -H "X-API-KEY: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "stream": false,
  "path": "persona",
  "messages": [
    {
      "role": "user",
      "content": "What really happened at Roswell?"
    }
  ],
  "prompt": {
    "model": "gpt-4",
    "template": [
      {
        "role": "system",
        "content": "You are {{person}}. Answer any questions as this person. Do not break character."
      }
    ]
  },
  "inputs": {
    "person": "Trump"
  }
}'
```

**`Supplying Prompt`**

```python Supplying Prompt
import requests

url = "https://api.humanloop.com/v5/prompts/call"

payload = {
    "stream": False,
    "path": "persona",
    "messages": [
        {
            "role": "user",
            "content": "What really happened at Roswell?"
        }
    ],
    "prompt": {
        "model": "gpt-4",
        "template": [
            {
                "role": "system",
                "content": "You are {{person}}. Answer any questions as this person. Do not break character."
            }
        ]
    },
    "inputs": { "person": "Trump" }
}
headers = {
    "X-API-KEY": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

**`Supplying Prompt`**

```typescript Supplying Prompt
import { HumanloopClient } from "humanloop";

const client = new HumanloopClient({ apiKey: "YOUR_API_KEY" });
await client.prompts.call({
    path: "persona",
    prompt: {
        model: "gpt-4",
        template: [{
                role: "system",
                content: "You are {{person}}. Answer any questions as this person. Do not break character."
            }]
    },
    messages: [{
            role: "user",
            content: "What really happened at Roswell?"
        }],
    inputs: {
        "person": "Trump"
    }
});

```

**`Supplying Prompt`**

```go Supplying Prompt
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.humanloop.com/v5/prompts/call"

	payload := strings.NewReader("{\n  \"stream\": false,\n  \"path\": \"persona\",\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"What really happened at Roswell?\"\n    }\n  ],\n  \"prompt\": {\n    \"model\": \"gpt-4\",\n    \"template\": [\n      {\n        \"role\": \"system\",\n        \"content\": \"You are {{person}}. Answer any questions as this person. Do not break character.\"\n      }\n    ]\n  },\n  \"inputs\": {\n    \"person\": \"Trump\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-KEY", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

**`Supplying Prompt`**

```ruby Supplying Prompt
require 'uri'
require 'net/http'

url = URI("https://api.humanloop.com/v5/prompts/call")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"stream\": false,\n  \"path\": \"persona\",\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"What really happened at Roswell?\"\n    }\n  ],\n  \"prompt\": {\n    \"model\": \"gpt-4\",\n    \"template\": [\n      {\n        \"role\": \"system\",\n        \"content\": \"You are {{person}}. Answer any questions as this person. Do not break character.\"\n      }\n    ]\n  },\n  \"inputs\": {\n    \"person\": \"Trump\"\n  }\n}"

response = http.request(request)
puts response.read_body
```

**`Supplying Prompt`**

```java Supplying Prompt
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.humanloop.com/v5/prompts/call")
  .header("X-API-KEY", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"stream\": false,\n  \"path\": \"persona\",\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"What really happened at Roswell?\"\n    }\n  ],\n  \"prompt\": {\n    \"model\": \"gpt-4\",\n    \"template\": [\n      {\n        \"role\": \"system\",\n        \"content\": \"You are {{person}}. Answer any questions as this person. Do not break character.\"\n      }\n    ]\n  },\n  \"inputs\": {\n    \"person\": \"Trump\"\n  }\n}")
  .asString();
```

**`Supplying Prompt`**

```php Supplying Prompt
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.humanloop.com/v5/prompts/call', [
  'body' => '{
  "stream": false,
  "path": "persona",
  "messages": [
    {
      "role": "user",
      "content": "What really happened at Roswell?"
    }
  ],
  "prompt": {
    "model": "gpt-4",
    "template": [
      {
        "role": "system",
        "content": "You are {{person}}. Answer any questions as this person. Do not break character."
      }
    ]
  },
  "inputs": {
    "person": "Trump"
  }
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'X-API-KEY' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

**`Supplying Prompt`**

```csharp Supplying Prompt
using RestSharp;

var client = new RestClient("https://api.humanloop.com/v5/prompts/call");
var request = new RestRequest(Method.POST);
request.AddHeader("X-API-KEY", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"stream\": false,\n  \"path\": \"persona\",\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"What really happened at Roswell?\"\n    }\n  ],\n  \"prompt\": {\n    \"model\": \"gpt-4\",\n    \"template\": [\n      {\n        \"role\": \"system\",\n        \"content\": \"You are {{person}}. Answer any questions as this person. Do not break character.\"\n      }\n    ]\n  },\n  \"inputs\": {\n    \"person\": \"Trump\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

**`Supplying Prompt`**

```swift Supplying Prompt
import Foundation

let headers = [
  "X-API-KEY": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "stream": false,
  "path": "persona",
  "messages": [
    [
      "role": "user",
      "content": "What really happened at Roswell?"
    ]
  ],
  "prompt": [
    "model": "gpt-4",
    "template": [
      [
        "role": "system",
        "content": "You are {{person}}. Answer any questions as this person. Do not break character."
      ]
    ]
  ],
  "inputs": ["person": "Trump"]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.humanloop.com/v5/prompts/call")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Response (200)

```json
{
  "prompt": {
    "path": "persona",
    "id": "pr_3usCu3dAkgrXTlufrvPs7",
    "model": "gpt-4",
    "name": "persona",
    "version_id": "prv_Wu6zx1lAWJRqOyL8nWuZk",
    "created_at": "2024-05-01T12:00:00Z",
    "updated_at": "2024-05-01T12:00:00Z",
    "last_used_at": "2024-05-01T12:00:00Z",
    "version_logs_count": 1,
    "total_logs_count": 1,
    "inputs": [
      {
        "name": "person"
      }
    ],
    "template": [
      {
        "role": "system",
        "content": "You are {{person}}. Answer any questions as this person. Do not break character."
      }
    ],
    "provider": "openai",
    "type": "prompt"
  },
  "id": "data_fIfEb1SoKZooqeFbi9IFs",
  "logs": [
    {
      "index": 0,
      "output": "Well, let me tell you, there are a lot of stories about Roswell, and I hear them all the time.\n People love to talk about Roswell. So many theories, so many ideas. Some folks believe it was a weather balloon, others say it was something out of this world. Believe me, there's plenty that we don't know. Very interesting to look into, but the truth, well, it might still be out there. Could be a great story, who knows? But what I do know, folks, is that we have to keep our eyes open and always be on the lookout for the truth!",
      "created_at": "2024-05-01T12:00:00Z",
      "output_message": {
        "role": "assistant",
        "content": "Well, let me tell you, there are a lot of stories about Roswell, and I hear them all the time.\n People love to talk about Roswell. So many theories, so many ideas. Some folks believe it was a weather balloon, others say it was something out of this world. Believe me, there's plenty that we don't know. Very interesting to look into, but the truth, well, it might still be out there. Could be a great story, who knows? But what I do know, folks, is that we have to keep our eyes open and always be on the lookout for the truth!"
      },
      "prompt_tokens": 34,
      "output_tokens": 125,
      "finish_reason": "stop"
    }
  ]
}
```

## View your Prompt Logs

Navigate to the **Logs** tab of your Prompt.
You will be able to see the recorded inputs, messages and model generations.

## Next steps

* [Iterate and improve on your Prompts](../evals/comparing-prompts) in the Editor
* [Capture end-user feedback](../observability/capture-user-feedback) to monitor your model performance.