# Source: https://docs.promptlayer.com/running-requests/promptlayer-run.md

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.promptlayer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Run

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

<Note>
  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.
</Note>

<Accordion title="Provider-Specific Configuration">
  ### 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"`
</Accordion>

<CodeGroup>
  ```python Python theme={null}
  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"])
  ```

  ```js JavaScript theme={null}
  import { PromptLayer } from "promptlayer";

  const pl = new PromptLayer({ apiKey: "your_api_key" });

  const response = await pl.run({
    promptName: "your-prompt-name",
    inputVariables: { variableName: "value" }
  });

  console.log(response.prompt_blueprint.prompt_template.messages.slice(-1)[0].content.slice(-1)[0].text);
  ```
</CodeGroup>

## 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:

<CodeGroup>
  ```python Python theme={null}
  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']}")
  ```

  ```js JavaScript theme={null}
  const stream = await pl.run({
    promptName: "your-prompt",
    stream: true
  });

  for await (const chunk of stream) {
    // Access raw streaming response
    console.log(chunk.raw_response);
    
    // Access progressively built prompt blueprint
    if (chunk.prompt_blueprint) {
      const currentResponse = chunk.prompt_blueprint.prompt_template.messages.slice(-1)[0];
      if (currentResponse.content) {
        console.log("Current response:", currentResponse.content);
      }
    }
  }
  ```
</CodeGroup>

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

<CodeGroup>
  ```python Python theme={null}
  response = pl.run(
      prompt_name="your-prompt",
      prompt_version=2,  # or
      prompt_release_label="staging"
  )
  ```

  ```js JavaScript theme={null}
  const response = await pl.run({
    promptName: "your-prompt",
    promptVersion: 2,  // or
    promptReleaseLabel: "staging"
  });
  ```
</CodeGroup>

### Adding Tags and Metadata

<CodeGroup>
  ```python Python theme={null}
  response = pl.run(
      prompt_name="your-prompt",
      tags=["test", "experiment"],
      metadata={"user_id": "12345"}
  )
  ```

  ```js JavaScript theme={null}
  const response = await pl.run({
    promptName: "your-prompt",
    tags: ["test", "experiment"],
    metadata: { userId: "12345" }
  });
  ```
</CodeGroup>

### 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 correct `llm_kwargs` for the specified provider and model with default values for the parameters corresponding to the `provider` and `model`.

<Warning>
  **Provider-Specific Schema Notice**

  The `llm_kwargs` and `raw_response` objects have provider-specific structures that may change as LLM providers update their APIs. PromptLayer passes through the native format required by each provider.

  For stable, provider-agnostic prompt data, use `prompt_blueprint.prompt_template` instead of relying on the structure of provider-specific objects.
</Warning>

<CodeGroup>
  ```python Python SDK theme={null}
  response = pl.run(
      prompt_name="your-prompt",
      provider="openai",  # or "anthropic", "google", etc.
      model="gpt-4",  # or "claude-2", "gemini-1.5-pro", etc.
  )
  ```

  ```js JavaScript theme={null}
  const response = await pl.run({
    promptName: "your-prompt",
    provider: "openai",  // or "anthropic", "google", etc.
    model: "gpt-4"  // or "claude-2", "gemini-1.5-pro", etc.
  });
  ```
</CodeGroup>

<Tip>
  Make sure to set both `model` and `provider` in order to run the request against correct LLM provider with correct parameters.
</Tip>