Skip to main content
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: 
{
  "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

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

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

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

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

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

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