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

# Metering Events

> Send actions and outcomes via API

## Send Action

<ParamField path="POST" type="string" required>
  /v1/actions
</ParamField>

Send an action event.

### Body

<ParamField body="agent_key" type="string" required>
  Agent instance key
</ParamField>

<ParamField body="action_type" type="string" required>
  Action type (llm\_call, tool\_call, etc.)
</ParamField>

<ParamField body="metadata" type="object">
  Action metadata (key-value pairs)
</ParamField>

<ParamField body="timestamp" type="string">
  Event timestamp (ISO 8601, defaults to now)
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl -X POST https://api.valmi.io/v1/actions \
    -H "Authorization: Bearer sk_api_abc123xyz" \
    -H "Content-Type: application/json" \
    -d '{
      "agent_key": "agent_abc123xyz",
      "action_type": "llm_call",
      "metadata": {
        "model": "gpt-4",
        "input_tokens": 1000,
        "output_tokens": 500
      }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "action_xyz789",
    "status": "processed",
    "created_at": "2024-01-15T10:30:00Z"
  }
  ```
</ResponseExample>

## Send Outcome

<ParamField path="POST" type="string" required>
  /v1/outcomes
</ParamField>

Send an outcome event.

### Body

<ParamField body="agent_key" type="string" required>
  Agent instance key
</ParamField>

<ParamField body="outcome_type" type="string" required>
  Outcome type (successful\_hire, converted\_lead, etc.)
</ParamField>

<ParamField body="value" type="number" required>
  Outcome value (count or amount)
</ParamField>

<ParamField body="metadata" type="object">
  Outcome metadata
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl -X POST https://api.valmi.io/v1/outcomes \
    -H "Authorization: Bearer sk_api_abc123xyz" \
    -H "Content-Type: application/json" \
    -d '{
      "agent_key": "agent_abc123xyz",
      "outcome_type": "successful_hire",
      "value": 1,
      "metadata": {
        "candidate_id": "cand_123"
      }
    }'
  ```
</RequestExample>