Skip to main content
The run() method is a core function of the PromptLayer SDK, allowing you to execute prompts and interact with various LLM providers using a unified interface.

​
Basic Usage

For any LLM provider you plan to use, you must set its corresponding API key as an environment variable (for example, OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY etc.). The PromptLayer client does not support passing these keys directly in code. If the relevant environment variables are not set, any requests to those LLM providers will fail.

​
Using Gemini models through Vertex AI

Python SDK: Set these environment variables:
  • GOOGLE_GENAI_USE_VERTEXAI=true
  • GOOGLE_CLOUD_PROJECT="<google_cloud_project_id>"
  • GOOGLE_CLOUD_LOCATION="region"
  • GOOGLE_APPLICATION_CREDENTIALS="path/to/google_service_account_file.json"
JavaScript SDK: Set these environment variables:
  • VERTEX_AI_PROJECT_ID="<google_cloud_project_id>"
  • VERTEX_AI_PROJECT_LOCATION="region"
  • GOOGLE_APPLICATION_CREDENTIALS="path/to/google_service_account_file.json"

​
Using Claude models through Vertex AI

Python SDK: Set these environment variables:
  • ANTHROPIC_VERTEX_PROJECT_ID="<google_cloud_project_id>"
  • CLOUD_ML_REGION="region"
  • GOOGLE_APPLICATION_CREDENTIALS="path/to/google_service_account_file.json"
JavaScript SDK: Set these environment variables:
  • GOOGLE_APPLICATION_CREDENTIALS="path/to/google_service_account_file.json"
  • CLOUD_ML_REGION="region"
from promptlayer import PromptLayer

pl = PromptLayer(api_key="your_api_key")

response = pl.run(
    prompt_name="your-prompt-name",
    input_variables={"variable_name": "value"}
)

print(response["prompt_blueprint"]["prompt_template"]["messages"][-1]["content"][-1]["text"])

​
Parameters

  • prompt_name / promptName (str, required): The name of the prompt to run.
  • prompt_version / promptVersion (int, optional): Specific version of the prompt to use.
  • prompt_release_label / promptReleaseLabel (str, optional): Release label of the prompt (e.g., “prod”, “staging”).
  • input_variables / inputVariables (Dict[str, Any], optional): Variables to be inserted into the prompt template.
  • tags (List[str], optional): Tags to associate with this run.
  • metadata (Dict[str, str], optional): Additional metadata for the run.
  • group_id / groupId (int, optional): Group ID to associate with this run.
  • model_parameter_overrides / modelParameterOverrides (Union[Dict[str, Any], None], optional): Model-specific parameter overrides.
  • stream (bool, default=False): Whether to stream the response.
  • provider (str, optional): The LLM provider to use (e.g., “openai”, “anthropic”, “google”). This is useful if you want to override the provider specified in the prompt template.
  • model (str, optional): The model to use (e.g., “gpt-4o”, “claude-3-7-sonnet-latest”, “gemini-2.5-flash”). This is useful if you want to override the model specified in the prompt template.

​
Return Value

The method returns a dictionary (Python) or object (JavaScript) with the following keys:
  • request_id: Unique identifier for the request.
  • raw_response: The raw response from the LLM provider.
  • prompt_blueprint: The prompt blueprint used for the request.

​
Advanced Usage

​
Streaming

To stream the response: 
for chunk in pl.run(prompt_name="your-prompt", stream=True):
    # Access raw streaming response
    print(chunk["raw_response"])
    
    # Access progressively built prompt blueprint
    if chunk["prompt_blueprint"]:
        current_response = chunk["prompt_blueprint"]["prompt_template"]["messages"][-1]
        if current_response.get("content"):
            print(f"Current response: {current_response['content']}")
When streaming is enabled, each chunk includes both the raw streaming response and the progressively built prompt_blueprint, allowing you to track how the response is constructed in real-time. The request_id is only included in the final chunk.

​
Using Different Versions or Release Labels

response = pl.run(
    prompt_name="your-prompt",
    prompt_version=2,  # or
    prompt_release_label="staging"
)

​
Adding Tags and Metadata

response = pl.run(
    prompt_name="your-prompt",
    tags=["test", "experiment"],
    metadata={"user_id": "12345"}
)

​
Overriding Model Parameters

You can also override provider and model at runtime to choose a different LLM provider or model. This is useful if you want to use a different provider than the one specified in the prompt template. PromptLayer will automatically return the corrent llm_kwargs for the specified provider and model with default values for the parameters corresponding to the provider and model. 
response = pl.run(
    prompt_name="your-prompt",
    provider="openai",  # or "anthropic", "google", etc.
    model="gpt-4",  # or "claude-2", "gemini-1.5-pro", etc.
)
Make sure to set both model and provider in order to run the request against correct LLM provider with correct parameters.