> 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 use the Humanloop Python SDK to sample a subset of your Logs and create an Evaluation Run to spot-check them.

By regularly reviewing a sample of your Prompt Logs, you can gain valuable insights into the performance of your
Prompts in production, such as through reviews by subject-matter experts (SMEs).

> **Info**
>
> For real-time observability (typically using code Evaluators), see our guide
> on setting up [monitoring](../observability/monitoring). This guide describes
> setting up more detailed evaluations which are run on a small subset of Logs.

### Prerequisites

* You have a Prompt with Logs. See our guide on [logging to a Prompt](/docs/guides/prompts/log-to-a-prompt) if you don't yet have one.
* You have a Human Evaluator set up. See our guide on [creating a Human Evaluator](/docs/guides/evals/human-evaluators) if you don't yet have one.

#### 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());
```

## Set up an Evaluation

### Create an Evaluation

Create an Evaluation for the Prompt.
In this example, we also attach a "rating" Human Evaluator so our SMEs can judge the generated responses.

```python
evaluation = humanloop.evaluations.create(
    # Name your Evaluation
    name="Monthly spot-check",
    file={
        # Replace this with the ID of your Prompt.
        # You can specify a Prompt by "path" as well.
        "id": "pr_..."
    },
    evaluators=[
        # Attach Evaluator to enable SMEs to rate the generated responses
        {"path": "Example Evaluators/Human/rating"},
    ],
)
```

### Create a Run

Create a Run within the Evaluation. We will then attach Logs to this Run.

```python
run = humanloop.evaluations.create_run(
    id=evaluation.id,
)
```

### Sample Logs

Sample a subset of your Logs to attach to the Run.

For this example, we'll sample 100 Logs from the past 30 days, simulating
a monthly spot-check.

```python
import datetime

logs = humanloop.logs.list(
    file_id="pr_...",  # Replace with the ID of the Prompt
    sample=100,
    # Example filter to sample Logs from the past 30 days
    start_date=datetime.datetime.now() - datetime.timedelta(days=30),
)

log_ids = [log.id for log in logs]
```

### Attach Logs to the Run

Attach the sampled Logs to the Run you created earlier.

```python
humanloop.evaluations.add_logs_to_run(
    id=evaluation.id,
    run_id=run.id,
    log_ids=log_ids,
)
```

You have now created an Evaluation Run with a sample of Logs attached to it.
In the Humanloop app, go to the Prompt's Evaluations tab. You should see the new Evaluation
named "Monthly spot-check". Click on it to view the Run with the Logs attached.

![Evaluation Run with Logs attached](/docs/_fern-img/29d705b4f442100162bc11ddb30b5a699164862fd80902f13941c4e44bb7eb79.webp)

## Review your Logs

Rate the model generations via the **Review** tab.

> **Info**
>
> For further details on how you can manage reviewing your Logs with multiple
> SMEs, see our guide on [managing multiple reviewers](./manage-multiple-reviewers).

![Logs review](/docs/_fern-img/999a6f4ddd300ed43486a3a8228568c954988a345a95e7195283e9539fcdb098.webp)

After your Logs have been reviewed, go to the **Stats** tab to view aggregate stats.

![Aggregate run stats](/docs/_fern-img/d6dc5235fdd3317485691ba8849668cde857024458159bb1da86e456e62dca3d.webp)

## Repeating the spot-check

To repeat this process the next time a spot-check is due, you can create a new Run within the same Evaluation,
repeating the above steps from "Create a Run". You will then see the new Run alongside the previous ones in the Evaluation,
and can compare the aggregate stats across multiple Runs.

## Next Steps

* If you have performed a spot-check and identified issues, you can [iterate on your Prompts in the app](./comparing-prompts) and [run further Evaluations](/docs/guides/evals/run-evaluation-ui) to verify improvements.