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

# Invoke metadata

> Pass caller-defined metadata to public invoke endpoints and use it to inspect and filter logs

Use invoke metadata when you want to attach your own audit fields to live prompt, workflow, or agent runs. Metadata is stored with the run, shown in log details, and available as **User metadata** filters in logs.

## Overview

Fetch Hive accepts a `metadata` object on these public invoke endpoints:

* `POST /v1/prompt/invoke`
* `POST /v1/workflow/invoke`
* `POST /v1/agent/invoke`

Use metadata for fields from your application that help you investigate and segment traffic later, such as customer IDs, plan names, regions, experiment names, environments, tenant IDs, or feature flags.

Metadata is not prompt, workflow, or agent input. Prompt variables and workflow start variables belong in `inputs`. Agent messages belong in `message` or `messages`.

## Metadata shape

`metadata` must be a flat object. Keys must be non-empty strings, and values must be strings, numbers, booleans, or `null`.

Nested objects and arrays are rejected before the run starts.

Good metadata examples:

```json theme={null}
{
  "customer_id": "cus_123",
  "plan": "enterprise",
  "region": "us-east-1",
  "experiment": "checkout_v2",
  "beta_user": true
}
```

Avoid sending sensitive data, secrets, raw user messages, or large payloads in metadata. Keep it small and stable so filters stay useful.

## cURL examples

### Prompt invoke

```bash theme={null}
curl 'https://api.fetchhive.com/v1/prompt/invoke' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "deployment": "support-classifier",
    "variant": "default",
    "inputs": {
      "ticket_text": "The export button is disabled."
    },
    "metadata": {
      "customer_id": "cus_1234",
      "plan": "enterprise",
      "experiment": "support_triage_v2"
    }
  }'
```

### Workflow invoke

```bash theme={null}
curl 'https://api.fetchhive.com/v1/workflow/invoke' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "deployment": "research-brief",
    "variant": "default",
    "inputs": {
      "topic": "AI infrastructure trends"
    },
    "metadata": {
      "customer_id": "cus_123",
      "region": "us-east-1",
      "source": "daily_digest_job"
    }
  }'
```

### Agent invoke

```bash theme={null}
curl 'https://api.fetchhive.com/v1/agent/invoke' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "agent": "AGENT_UUID",
    "message": "Summarize this account before renewal.",
    "metadata": {
      "customer_id": "cus_123",
      "plan": "enterprise",
      "renewal_window_days": 30
    }
  }'
```

## SDK examples

The official SDKs accept the same `metadata` object on prompt, workflow, and agent invoke helpers.

### Node.js

```typescript theme={null}
import { FetchHive } from "@fetch-hive/sdk";

const client = new FetchHive({ apiKey: process.env.FETCH_HIVE_API_KEY });

const result = await client.invokePrompt({
  deployment: "support-classifier",
  variant: "default",
  inputs: { ticket_text: "The export button is disabled." },
  metadata: {
    customer_id: "cus_123",
    plan: "enterprise",
    experiment: "support_triage_v2",
  },
});

console.log(result.response);
```

Use the same field with `invokeWorkflow` and `invokeAgent`:

```typescript theme={null}
await client.invokeWorkflow({
  deployment: "research-brief",
  variant: "default",
  inputs: { topic: "AI infrastructure trends" },
  metadata: { customer_id: "cus_123", source: "daily_digest_job" },
});

await client.invokeAgent({
  agent: "AGENT_UUID",
  message: "Summarize this account before renewal.",
  metadata: { customer_id: "cus_123", renewal_window_days: 30 },
});
```

### Python

```python theme={null}
from fetch_hive_sdk import FetchHive

client = FetchHive()

result = client.invoke_prompt(
    deployment="support-classifier",
    variant="default",
    inputs={"ticket_text": "The export button is disabled."},
    metadata={
        "customer_id": "cus_123",
        "plan": "enterprise",
        "experiment": "support_triage_v2",
    },
)

print(result["response"])
```

Use the same argument with `invoke_workflow` and `invoke_agent`:

```python theme={null}
client.invoke_workflow(
    deployment="research-brief",
    variant="default",
    inputs={"topic": "AI infrastructure trends"},
    metadata={"customer_id": "cus_123", "source": "daily_digest_job"},
)

client.invoke_agent(
    agent="AGENT_UUID",
    message="Summarize this account before renewal.",
    metadata={"customer_id": "cus_123", "renewal_window_days": 30},
)
```

### Ruby

```ruby theme={null}
require "fetch_hive"

client = FetchHive::Client.new(api_key: ENV.fetch("FETCH_HIVE_API_KEY"))

result = client.invoke_prompt(
  deployment: "support-classifier",
  variant: "default",
  inputs: { ticket_text: "The export button is disabled." },
  metadata: {
    customer_id: "cus_123",
    plan: "enterprise",
    experiment: "support_triage_v2"
  }
)

puts result["response"]
```

### PHP

```php theme={null}
<?php
require_once 'vendor/autoload.php';

use FetchHive\Sdk\FetchHive;

$client = new FetchHive(['api_key' => getenv('FETCH_HIVE_API_KEY')]);

$result = $client->invokePrompt([
    'deployment' => 'support-classifier',
    'variant'    => 'default',
    'inputs'     => ['ticket_text' => 'The export button is disabled.'],
    'metadata'   => [
        'customer_id' => 'cus_123',
        'plan'        => 'enterprise',
        'experiment'  => 'support_triage_v2',
    ],
]);

echo $result['response'];
```

## Filtering logs by metadata

After runs arrive with metadata, open the matching log page:

* Prompt runs: open the prompt and select **Activity Logs**
* Workflow runs: open **Workflows** and select **Logs**
* Agent runs: open **Agents** and select **Logs**

Use **User metadata** to filter by metadata.

Choose a metadata key to find runs where that key exists. Add a value when you want an exact scalar match, such as `customer_id = cus_123`, `plan = enterprise`, `beta_user = true`, or `renewal_window_days = 30`.

Fetch Hive tracks metadata property names over time from invoke requests so the filter can suggest keys your workspace has actually sent. Older runs without that metadata remain visible normally, but they are excluded when a matching metadata filter is active.

When you open a run detail sheet, metadata appears in the **User metadata** section so you can confirm which caller-defined fields were attached to that run.

## See also

* [Invoke Prompt](../api-reference/prompts/invoke)
* [Invoke Workflow](../api-reference/workflows/invoke)
* [Invoke Agent](../api-reference/agents/invoke)
* [Prompt logs](../prompts/logs)
* [Workflow logs](../workflows/logs)
* [Agent logs](../agents/logs)