Test Rules

Tests a raw usage JSON sample against an extractor rule set and an optional pricing rule set. This endpoint is a dry run: it does not create raw events, usage events, charge items, wallet debits, or analytics rows.

POST /v1/projects/:project_id/rules/test

Authentication

Authorization: Bearer <api-key>
Content-Type: application/json

Requires rules test access.

Path Parameters

Field	Required	Description
project_id	Yes	Project used to scope the extractor and pricing rule sets.

Request Body

{
  "extractor_rule_set_id": "ers_openai",
  "pricing_rule_set_id": "prs_openai_fallback",
  "raw_json": {
    "type": "response",
    "provider": "openai",
    "usage": {
      "model": "gpt-4.1-mini",
      "prompt_tokens": 1200,
      "output_tokens": 300
    },
    "meta": {
      "user_id": "user_123",
      "org_id": "org_001"
    }
  }
}

Field	Required	Description
extractor_rule_set_id	No	Extractor rule set ID to test. Pass this when validating extraction.
pricing_rule_set_id	No	Pricing rule set ID to test against extracted charge items. Pass this when validating fallback pricing.
raw_json	Yes	Raw usage JSON sample. The endpoint validates extraction and pricing against this payload.

If pricing_rule_set_id is omitted, the endpoint validates extraction and attached extractor pricing. If the raw JSON includes x-pricing-rule and extracted items still need fallback rating, that pricing rule set is used.

Example

curl 'http://127.0.0.1:8080/v1/projects/proj_gateway/rules/test' \
  -X POST \
  -H 'Authorization: Bearer <api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "extractor_rule_set_id": "ers_openai",
    "pricing_rule_set_id": "prs_openai_fallback",
    "raw_json": {
      "type": "response",
      "provider": "openai",
      "usage": {
        "model": "gpt-4.1-mini",
        "prompt_tokens": 1200,
        "output_tokens": 300
      },
      "meta": {
        "user_id": "user_123",
        "org_id": "org_001"
      }
    }
  }'

Response

{
  "subject_type": "user",
  "subject_id": "user_123",
  "dimensions": {
    "provider": "openai",
    "model": "gpt-4.1-mini",
    "org_id": "org_001"
  },
  "charge_items": [
    {
      "id": "ci_01",
      "usage_event_id": "usage_01",
      "subject_type": "user",
      "metric": "input_tokens",
      "quantity": 1200,
      "unit": "token",
      "pricing_rule_set_id": "prs_openai_fallback",
      "pricing_version": 1,
      "matched_rule_id": "input_tokens",
      "currency": "USD",
      "unit_price": 0.0000002,
      "amount": 0.00024
    },
    {
      "id": "ci_02",
      "usage_event_id": "usage_01",
      "subject_type": "user",
      "metric": "output_tokens",
      "quantity": 300,
      "unit": "token",
      "pricing_rule_set_id": "prs_openai_fallback",
      "pricing_version": 1,
      "matched_rule_id": "output_tokens",
      "currency": "USD",
      "unit_price": 0.0000008,
      "amount": 0.00024
    }
  ],
  "unmatched_items": []
}

Notes

• Use this endpoint before publishing rules and after publishing when you want to verify the exact production rule version.
• unmatched_items contains charge items that were extracted but could not be rated by attached pricing, pricing_rule_set_id, or x-pricing-rule.