Sample Requests

Sample Requests (experimental) allows you to automatically forward a percentage of your API requests and responses to a webhook endpoint for analysis, monitoring, and quality assurance.

View request logs in the Requesty Console.

Overview

The Sample Requests feature enables you to capture a configurable percentage of chat completion requests and responses, forwarding them to your webhook URL for detailed analysis. This is useful for:

Quality Monitoring: Review AI responses for quality assurance
Analytics: Analyze request patterns and response characteristics

How to use

Request sampling is configured using the sample object within the requesty field when sending chat completion requests:

{
  "requesty": {
    "sample": {
      "webhook_url": "https://your-webhook-url.com/endpoint",
      "sample_ratio": 0.1
    }
  }
}

Parameters

webhook_url (required): The HTTPS endpoint URL where sampled requests and responses will be sent via HTTP POST
sample_ratio (required): A float between 0 and 1 (inclusive) representing the percentage of requests to sample
- 0.0: No requests sampled
- 0.1: 10% of requests sampled
- 1.0: 100% of requests sampled

Note: Your webhook could respond with a JSON payload with a feedback object containing string key-value pairs. And the entire object will be attached as feedback to the logs of the sampled request. All keys can only contain [a-z, A-Z, 0-9, -, _] and are up to 128 chars and all values must be valid strings representing either float, int64 or strings of the same constraints.

A concrete example

Chat completion request

curl --request POST \
  --url https://router.requesty.ai/v1/chat/completions \
  --header 'Authorization: Bearer YOUR_REQUESTY_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "openai/gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": "hello"
    }
  ],
  "requesty": {
    "sample": {
      "webhook_url": "https://your-webhook-url.com/endpoint",
      "sample_ratio": 1
    }
  }
}'

When a request is sampled, your webhook receives a POST request with the following structure where request and response conform to OpenAI Chat Completion API.

{
  "request_id": "...",
  "request": {
    "messages": [
      {
        "content": "hello",
        "role": "user"
      }
    ],
    "model": "openai/gpt-4o"
  },
  "response": {
    "choices": [
      {
        "finish_reason": "stop",
        "index": 0,
        "message": {
          "content": "Hello! How can I help you today?",
          "role": "assistant"
        }
      }
    ],
    "created": 1761758842,
    "id": "...",
    "model": "openai/gpt-4o",
    "object": "chat.completion",
    "usage": {
      "completion_tokens": 15,
      "prompt_tokens": 10,
      "total_tokens": 25,
      "cost": 0
    },
    "base_resp": {
      "status_code": 0,
      "status_msg": ""
    }
  }
}

Verifying sampled webhooks

If your organization has a webhook signing secret, each sampled webhook is signed with it. The webhook-id header matches the payload’s request_id, and the X-Requesty-Event header is sample.request. See Webhook Signatures for how to verify the signature.

Webhook response

An example of a valid webhook response.

{
  "feedback": {
    "thumbs": "up",
    "rating": "5",
  }
}

Getting Started

LLM Gateway

Model Capabilities

Analytics & Monitoring

Access Control

Organization

MCP Gateway

Overview

How to use

Parameters

A concrete example

Verifying sampled webhooks

Webhook response

​Overview

​How to use

​Parameters

​A concrete example

​Verifying sampled webhooks

​Webhook response

Overview

How to use

Parameters

A concrete example

Verifying sampled webhooks

Webhook response