Call a Prompt

A guide on 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:

Install the Humanloop SDK:

1 pip install humanloop

Initialize the SDK with your Humanloop API key (you can get it from the Organization Settings page).

1 from humanloop import Humanloop
2 humanloop = Humanloop(api_key="<YOUR HUMANLOOP KEY>")
3 
4 # Check that the authentication was successful
5 print(humanloop.prompts.list())

Call an existing Prompt

If you don’t have Prompt already on Humanloop, please follow our Prompt creation 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.

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 method in the SDK.

POST

/v5/prompts/call

1 curl -X POST "https://api.humanloop.com/v5/prompts/call?version_id=prv_Wu6zx1lAWJRqOyL8nWuZk" \
2      -H "X-API-KEY: <apiKey>" \
3      -H "Content-Type: application/json" \
4      -d '{
5   "path": "persona",
6   "messages": [
7     {
8       "role": "user",
9       "content": "What really happened at Roswell?"
10     }
11   ],
12   "inputs": {
13     "person": "Trump"
14   }
15 }'

Try it

Response

1 {
2   "prompt": {
3     "path": "persona",
4     "id": "pr_3usCu3dAkgrXTlufrvPs7",
5     "model": "gpt-4",
6     "name": "persona",
7     "version_id": "prv_Wu6zx1lAWJRqOyL8nWuZk",
8     "created_at": "2024-05-01T12:00:00Z",
9     "updated_at": "2024-05-01T12:00:00Z",
10     "last_used_at": "2024-05-01T12:00:00Z",
11     "version_logs_count": 1,
12     "total_logs_count": 1,
13     "inputs": [
14       {
15         "name": "person"
16       }
17     ],
18     "template": [
19       {
20         "role": "system",
21         "content": "You are {{person}}. Answer any questions as this person. Do not break character."
22       }
23     ],
24     "provider": "openai",
25     "type": "prompt"
26   },
27   "id": "data_fIfEb1SoKZooqeFbi9IFs",
28   "logs": [
29     {
30       "index": 0,
31       "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!",
32       "created_at": "2024-05-01T12:00:00Z",
33       "output_message": {
34         "role": "assistant",
35         "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!"
36       },
37       "prompt_tokens": 34,
38       "output_tokens": 125,
39       "finish_reason": "stop"
40     }
41   ]
42 }

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.

POST

/v5/prompts/call

1 curl -X POST https://api.humanloop.com/v5/prompts/call \
2      -H "X-API-KEY: <apiKey>" \
3      -H "Content-Type: application/json" \
4      -d '{
5   "stream": false,
6   "path": "persona",
7   "messages": [
8     {
9       "role": "user",
10       "content": "What really happened at Roswell?"
11     }
12   ],
13   "prompt": {
14     "model": "gpt-4",
15     "template": [
16       {
17         "role": "system",
18         "content": "You are {{person}}. Answer any questions as this person. Do not break character."
19       }
20     ]
21   },
22   "inputs": {
23     "person": "Trump"
24   }
25 }'

Try it

Response

1 {
2   "prompt": {
3     "path": "persona",
4     "id": "pr_3usCu3dAkgrXTlufrvPs7",
5     "model": "gpt-4",
6     "name": "persona",
7     "version_id": "prv_Wu6zx1lAWJRqOyL8nWuZk",
8     "created_at": "2024-05-01T12:00:00Z",
9     "updated_at": "2024-05-01T12:00:00Z",
10     "last_used_at": "2024-05-01T12:00:00Z",
11     "version_logs_count": 1,
12     "total_logs_count": 1,
13     "inputs": [
14       {
15         "name": "person"
16       }
17     ],
18     "template": [
19       {
20         "role": "system",
21         "content": "You are {{person}}. Answer any questions as this person. Do not break character."
22       }
23     ],
24     "provider": "openai",
25     "type": "prompt"
26   },
27   "id": "data_fIfEb1SoKZooqeFbi9IFs",
28   "logs": [
29     {
30       "index": 0,
31       "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!",
32       "created_at": "2024-05-01T12:00:00Z",
33       "output_message": {
34         "role": "assistant",
35         "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!"
36       },
37       "prompt_tokens": 34,
38       "output_tokens": 125,
39       "finish_reason": "stop"
40     }
41   ]
42 }

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 in the Editor
Capture end-user feedback to monitor your model performance.

1	from humanloop import Humanloop
2	humanloop = Humanloop(api_key="<YOUR HUMANLOOP KEY>")
3
4	# Check that the authentication was successful
5	print(humanloop.prompts.list())

1	curl -X POST "https://api.humanloop.com/v5/prompts/call?version_id=prv_Wu6zx1lAWJRqOyL8nWuZk" \
2	-H "X-API-KEY: <apiKey>" \
3	-H "Content-Type: application/json" \
4	-d '{
5	"path": "persona",
6	"messages": [
7	{
8	"role": "user",
9	"content": "What really happened at Roswell?"
10	}
11	],
12	"inputs": {
13	"person": "Trump"
14	}
15	}'

1	{
2	"prompt": {
3	"path": "persona",
4	"id": "pr_3usCu3dAkgrXTlufrvPs7",
5	"model": "gpt-4",
6	"name": "persona",
7	"version_id": "prv_Wu6zx1lAWJRqOyL8nWuZk",
8	"created_at": "2024-05-01T12:00:00Z",
9	"updated_at": "2024-05-01T12:00:00Z",
10	"last_used_at": "2024-05-01T12:00:00Z",
11	"version_logs_count": 1,
12	"total_logs_count": 1,
13	"inputs": [
14	{
15	"name": "person"
16	}
17	],
18	"template": [
19	{
20	"role": "system",
21	"content": "You are {{person}}. Answer any questions as this person. Do not break character."
22	}
23	],
24	"provider": "openai",
25	"type": "prompt"
26	},
27	"id": "data_fIfEb1SoKZooqeFbi9IFs",
28	"logs": [
29	{
30	"index": 0,
31	"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!",
32	"created_at": "2024-05-01T12:00:00Z",
33	"output_message": {
34	"role": "assistant",
35	"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!"
36	},
37	"prompt_tokens": 34,
38	"output_tokens": 125,
39	"finish_reason": "stop"
40	}
41	]
42	}

1	curl -X POST https://api.humanloop.com/v5/prompts/call \
2	-H "X-API-KEY: <apiKey>" \
3	-H "Content-Type: application/json" \
4	-d '{
5	"stream": false,
6	"path": "persona",
7	"messages": [
8	{
9	"role": "user",
10	"content": "What really happened at Roswell?"
11	}
12	],
13	"prompt": {
14	"model": "gpt-4",
15	"template": [
16	{
17	"role": "system",
18	"content": "You are {{person}}. Answer any questions as this person. Do not break character."
19	}
20	]
21	},
22	"inputs": {
23	"person": "Trump"
24	}
25	}'