VHGENGINE

by app.railway.up.engine-production-3bdc

export_usage

Read-only

Export ledger, hook, instance, lineage, outcome, profile, and retained-job data. Free; run BEFORE delete_account. Same JSON body as GET /v1/usage/export; CSV has events. UNBOUNDED: prefer paged reads on big accounts. Email is masked without admin scope. Returns account/email/count, ledger, hooks, instances, lineage, outcomes, jobs, profiles, source_evidence, and corrupt markers. Jobs and profiles retain their bounded receipts. Source evidence includes metrics, retractions, and separate research/extraction results. Filters narrow ledger events only; all retained data categories stay complete. Errors: unauthorized, forbidden (key lacks read scope), rate_limited.

Input Schema

TableJSON Schema

Name	Required	Description
`tag`	No	Filter to rows carrying EXACTLY this fleet tag (exact match, not a substring). Omit for every tag.
`api_key`	No	API key for this call. Omit to fall back to the Authorization: Bearer / X-API-Key request header (streamable-HTTP only), then the VHGENGINE_API_KEY env var (the stdio default). No key resolvable -> unauthorized.
`key_prefix`	No	Narrow the LEDGER to charges made with ONE api key, identified by the 12-char prefix from list_keys. `hooks`, `hook_instances`, `hook_lineage`, `outcomes`, `jobs`, `creator_profiles`, and `source_evidence` are always the full set and are NOT narrowed by this. Omit for every key.

Output Schema

TableJSON Schema

Name	Required	Description
`jobs`	No	Every currently retained async job, including exact commission snapshots, including schema-v2 capture-only intent when supplied, bounded request metadata, results, errors, and corruption markers. Rolling v1 execution views and worker charge identities are not presented as the accepted snapshot.
`count`	No	Number of usage-ledger rows in events after event filters.
`email`	No	Contact email in full for an admin-scoped key and masked for a read-only key.
`hooks`	No	Every currently retained hook, not narrowed by event filters.
`events`	No	Usage-ledger rows, oldest first, narrowed by event filters.
`outcomes`	No	Every retained outcome, not narrowed by event filters.
`account_id`	No	The exporting account id.
`hook_lineage`	No	Non-prose per-hook minimum occurrence counts retained until account deletion so expired or rolling-version rows cannot become falsely exact.
`corrupt_fields`	No	Bounded markers for retained event, hook, or outcome JSON fields that could not be decoded safely. Raw malformed values and row identifiers are not echoed.
`hook_instances`	No	Every immutable served-hook occurrence currently retained, including non-prose profile/version lineage when one was used. Unreferenced instances follow the hook TTL; every retained instance for a hook with any outcome remains so historical ambiguity cannot become false exactness.
`source_evidence`	No	Immutable source observations, bounded exact extracts, and candidate-to-served lineage. Corrupt parent chains are suppressed without echoing raw values.
`creator_profiles`	No	Every retained creator-profile version and consent event, plus bounded retraction markers for profiles whose direct declarations were erased.

Schema Changelog

Changes observed during successful MCP inspections.

Changed8 schema fields changedAug 10, 2026

changedOutput schema / properties / source_evidence / properties / corrupt_fields / items / properties / category / enum

Previous value: -[
-  "source_asset",
-  "extract",
-  "evidence_edge",
-  "legacy_lineage"
-]New value: +[
+  "source_asset",
+  "extract",
+  "evidence_edge",
+  "source_metric_observation",
+  "source_retraction_event",
+  "research_result",
+  "research_evidence_occurrence",
+  "extraction_result",
+  "extraction_occurrence",
+  "legacy_lineage"
+]

addedOutput schema / properties / source_evidence / properties / extraction_occurrences

Added value: +{
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "created_at": {
+        "format": "date-time",
+        "type": "string"
+      },
+      "extract_id": {
+        "pattern": "^ext_[0-9a-f]{24}$",
+        "type": "string"
+      },
+      "extraction_occurrence_id": {
+        "pattern": "^xoc_[0-9a-f]{24}$",
+        "type": "string"
+      },
+      "extraction_result_id": {
+        "pattern": "^xrs_[0-9a-f]{24}$",
+        "type": "string"
+      },
+      "item_index": {
+        "minimum": 0,
+        "type": "integer"
+      },
+      "served_hook_instance_id": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "source_asset_id": {
+        "pattern": "^sat_[0-9a-f]{24}$",
+        "type": "string"
+      }
+    },
+    "required": [
+      "extraction_occurrence_id",
+      "extraction_result_id",
+      "item_index",
+      "source_asset_id",
+      "extract_id",
+      "served_hook_instance_id",
+      "created_at"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

addedOutput schema / properties / source_evidence / properties / extraction_results

Added value: +{
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "caller_source_sha256": {
+        "pattern": "^[0-9a-f]{64}$",
+        "type": "string"
+      },
+      "charge_resource": {
+        "const": "extract_hook_candidates",
+        "type": "string"
+      },
+      "created_at": {
+        "format": "date-time",
+        "type": "string"
+      },
+      "excerpt_policy_sha256": {
+        "pattern": "^[0-9a-f]{64}$",
+        "type": "string"
+      },
+      "extraction_result_id": {
+        "pattern": "^xrs_[0-9a-f]{24}$",
+        "type": "string"
+      },
+      "idempotency_scope": {
+        "const": "extract_hook_candidates",
+        "type": "string"
+      },
+      "job_id": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "operation_kind": {
+        "const": "extract_hook_candidates",
+        "type": "string"
+      },
+      "request_id": {
+        "type": "string"
+      },
+      "result_sha256": {
+        "pattern": "^[0-9a-f]{64}$",
+        "type": "string"
+      },
+      "retention_state": {
+        "enum": [
+          "active",
+          "retracted",
+          "account_deassociated"
+        ],
+        "type": "string"
+      },
+      "retracted_at": {
+        "format": "date-time",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "retraction_reason": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "schema_version": {
+        "minimum": 1,
+        "type": "integer"
+      }
+    },
+    "required": [
+      "extraction_result_id",
+      "schema_version",
+      "operation_kind",
+      "request_id",
+      "job_id",
+      "idempotency_scope",
+      "charge_resource",
+      "caller_source_sha256",
+      "excerpt_policy_sha256",
+      "retention_state",
+      "result_sha256",
+      "retracted_at",
+      "retraction_reason",
+      "created_at"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

addedOutput schema / properties / source_evidence / properties / research_evidence_occurrences

Added value: +{
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "candidate_id": {
+        "type": "string"
+      },
+      "created_at": {
+        "format": "date-time",
+        "type": "string"
+      },
+      "extract_id": {
+        "pattern": "^ext_[0-9a-f]{24}$",
+        "type": "string"
+      },
+      "item_index": {
+        "minimum": 0,
+        "type": "integer"
+      },
+      "policy_bundle_sha256": {
+        "pattern": "^[0-9a-f]{64}$",
+        "type": "string"
+      },
+      "research_evidence_occurrence_id": {
+        "pattern": "^reo_[0-9a-f]{24}$",
+        "type": "string"
+      },
+      "research_result_id": {
+        "pattern": "^rrs_[0-9a-f]{24}$",
+        "type": "string"
+      },
+      "selected_rank": {
+        "minimum": 1,
+        "type": "integer"
+      },
+      "served_hook_instance_id": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "source_asset_id": {
+        "pattern": "^sat_[0-9a-f]{24}$",
+        "type": "string"
+      }
+    },
+    "required": [
+      "research_evidence_occurrence_id",
+      "research_result_id",
+      "item_index",
+      "selected_rank",
+      "candidate_id",
+      "source_asset_id",
+      "extract_id",
+      "served_hook_instance_id",
+      "policy_bundle_sha256",
+      "created_at"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

addedOutput schema / properties / source_evidence / properties / research_results

Added value: +{
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "charge_resource": {
+        "const": "research_hook_evidence",
+        "type": "string"
+      },
+      "commission_id": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "created_at": {
+        "format": "date-time",
+        "type": "string"
+      },
+      "idempotency_scope": {
+        "const": "research_hook_evidence",
+        "type": "string"
+      },
+      "job_id": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "operation_kind": {
+        "const": "research_hook_evidence",
+        "type": "string"
+      },
+      "request_id": {
+        "type": "string"
+      },
+      "research_result_id": {
+        "pattern": "^rrs_[0-9a-f]{24}$",
+        "type": "string"
+      },
+      "result_sha256": {
+        "pattern": "^[0-9a-f]{64}$",
+        "type": "string"
+      },
+      "retention_state": {
+        "enum": [
+          "active",
+          "retracted",
+          "account_deassociated"
+        ],
+        "type": "string"
+      },
+      "retracted_at": {
+        "format": "date-time",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "retraction_reason": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "retrieval_plan_id": {
+        "type": "string"
+      },
+      "run_id": {
+        "type": "string"
+      },
+      "schema_version": {
+        "minimum": 1,
+        "type": "integer"
+      }
+    },
+    "required": [
+      "research_result_id",
+      "schema_version",
+      "operation_kind",
+      "commission_id",
+      "retrieval_plan_id",
+      "run_id",
+      "request_id",
+      "job_id",
+      "idempotency_scope",
+      "charge_resource",
+      "retention_state",
+      "result_sha256",
+      "retracted_at",
+      "retraction_reason",
+      "created_at"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

addedOutput schema / properties / source_evidence / properties / source_metric_observations

Added value: +{
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "ad_state": {
+        "enum": [
+          "organic",
+          "advertisement",
+          "paid_partnership",
+          "unknown"
+        ],
+        "type": "string"
+      },
+      "author_country_code": {
+        "pattern": "^[A-Z]{2}$",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "author_country_evidence": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "comments": {
+        "minimum": 0,
+        "type": [
+          "integer",
+          "null"
+        ]
+      },
+      "content_market_code": {
+        "pattern": "^[A-Z]{2}$",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "content_market_evidence": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "created_at": {
+        "format": "date-time",
+        "type": "string"
+      },
+      "creator_followers": {
+        "minimum": 0,
+        "type": [
+          "integer",
+          "null"
+        ]
+      },
+      "engagement_horizon": {
+        "type": "string"
+      },
+      "likes": {
+        "minimum": 0,
+        "type": [
+          "integer",
+          "null"
+        ]
+      },
+      "metric_provenance": {
+        "type": "object"
+      },
+      "missing_fields": {
+        "items": {
+          "type": "string"
+        },
+        "type": "array",
+        "uniqueItems": true
+      },
+      "observation_sha256": {
+        "pattern": "^[0-9a-f]{64}$",
+        "type": "string"
+      },
+      "observed_at": {
+        "format": "date-time",
+        "type": "string"
+      },
+      "published_at": {
+        "format": "date-time",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "saves": {
+        "minimum": 0,
+        "type": [
+          "integer",
+          "null"
+        ]
+      },
+      "schema_version": {
+        "minimum": 1,
+        "type": "integer"
+      },
+      "shares": {
+        "minimum": 0,
+        "type": [
+          "integer",
+          "null"
+        ]
+      },
+      "source_asset_id": {
+        "pattern": "^sat_[0-9a-f]{24}$",
+        "type": "string"
+      },
+      "source_metric_observation_id": {
+        "pattern": "^smo_[0-9a-f]{24}$",
+        "type": "string"
+      },
+      "views": {
+        "minimum": 0,
+        "type": [
+          "integer",
+          "null"
+        ]
+      }
+    },
+    "required": [
+      "source_metric_observation_id",
+      "source_asset_id",
+      "schema_version",
+      "published_at",
+      "observed_at",
+      "engagement_horizon",
+      "views",
+      "likes",
+      "comments",
+      "shares",
+      "saves",
+      "creator_followers",
+      "ad_state",
+      "author_country_code",
+      "author_country_evidence",
+      "content_market_code",
+      "content_market_evidence",
+      "metric_provenance",
+      "missing_fields",
+      "observation_sha256",
+      "created_at"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

addedOutput schema / properties / source_evidence / properties / source_retraction_events

Added value: +{
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "created_at": {
+        "format": "date-time",
+        "type": "string"
+      },
+      "event_sha256": {
+        "pattern": "^[0-9a-f]{64}$",
+        "type": "string"
+      },
+      "event_type": {
+        "enum": [
+          "retracted",
+          "removed",
+          "restored"
+        ],
+        "type": "string"
+      },
+      "observed_at": {
+        "format": "date-time",
+        "type": "string"
+      },
+      "reason_code": {
+        "type": "string"
+      },
+      "schema_version": {
+        "minimum": 1,
+        "type": "integer"
+      },
+      "source_asset_id": {
+        "pattern": "^sat_[0-9a-f]{24}$",
+        "type": "string"
+      },
+      "source_retraction_event_id": {
+        "pattern": "^sre_[0-9a-f]{24}$",
+        "type": "string"
+      }
+    },
+    "required": [
+      "source_retraction_event_id",
+      "source_asset_id",
+      "schema_version",
+      "event_type",
+      "reason_code",
+      "observed_at",
+      "event_sha256",
+      "created_at"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

changedOutput schema / properties / source_evidence / required

Previous value: -[
-  "source_assets",
-  "extracts",
-  "evidence_edges",
-  "legacy_lineage",
-  "corrupt_fields"
-]New value: +[
+  "source_assets",
+  "extracts",
+  "evidence_edges",
+  "source_metric_observations",
+  "source_retraction_events",
+  "research_results",
+  "research_evidence_occurrences",
+  "extraction_results",
+  "extraction_occurrences",
+  "legacy_lineage",
+  "corrupt_fields"
+]

Changed3 schema fields changedAug 10, 2026

changedInput schema / properties / key_prefix / description

Previous value: -"Narrow the LEDGER to charges made with ONE api key, identified by the 12-char prefix from list_keys. `hooks`, `hook_instances`, `hook_lineage`, `outcomes`, `jobs`, and `creator_profiles` are always the full set and are NOT narrowed by this. Omit for every key."New value: +"Narrow the LEDGER to charges made with ONE api key, identified by the 12-char prefix from list_keys. `hooks`, `hook_instances`, `hook_lineage`, `outcomes`, `jobs`, `creator_profiles`, and `source_evidence` are always the full set and are NOT narrowed by this. Omit for every key."

changedOutput schema / description

Previous value: -"The account's usage-ledger, hook, outcome, retained-job, and creator-profile categories in one unbounded JSON body."New value: +"The account's usage-ledger, hook, outcome, retained-job, creator-profile, and source-evidence categories in one unbounded JSON body."

addedOutput schema / properties / source_evidence

Added value: +{
+  "additionalProperties": false,
+  "description": "Immutable source observations, bounded exact extracts, and candidate-to-served lineage. Corrupt parent chains are suppressed without echoing raw values.",
+  "properties": {
+    "corrupt_fields": {
+      "description": "Bounded markers for rows whose identifiers, canonical URL, timestamps, checksums, JSON snapshots, or lineage could not be safely projected. Malformed raw values are never echoed.",
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "category": {
+            "enum": [
+              "source_asset",
+              "extract",
+              "evidence_edge",
+              "legacy_lineage"
+            ],
+            "type": "string"
+          },
+          "row_index": {
+            "minimum": 0,
+            "type": "integer"
+          }
+        },
+        "required": [
+          "category",
+          "row_index"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "evidence_edges": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "candidate_id": {
+            "type": "string"
+          },
+          "commission_id": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "created_at": {
+            "format": "date-time",
+            "type": "string"
+          },
+          "evidence_edge_id": {
+            "pattern": "^edg_[0-9a-f]{24}$",
+            "type": "string"
+          },
+          "extract_id": {
+            "pattern": "^ext_[0-9a-f]{24}$",
+            "type": "string"
+          },
+          "hook_instance_id": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "item_index": {
+            "minimum": 0,
+            "type": [
+              "integer",
+              "null"
+            ]
+          },
+          "lineage_quality": {
+            "enum": [
+              "exact",
+              "legacy_ambiguous"
+            ],
+            "type": "string"
+          },
+          "request_id": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "run_id": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "source_asset_id": {
+            "pattern": "^sat_[0-9a-f]{24}$",
+            "type": "string"
+          }
+        },
+        "required": [
+          "evidence_edge_id",
+          "commission_id",
+          "run_id",
+          "request_id",
+          "item_index",
+          "candidate_id",
+          "source_asset_id",
+          "extract_id",
+          "hook_instance_id",
+          "lineage_quality",
+          "created_at"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "extracts": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "created_at": {
+            "format": "date-time",
+            "type": "string"
+          },
+          "cue_id": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "end_ms": {
+            "minimum": 1,
+            "type": [
+              "integer",
+              "null"
+            ]
+          },
+          "exact_text": {
+            "maxLength": 4096,
+            "type": "string"
+          },
+          "extract_id": {
+            "pattern": "^ext_[0-9a-f]{24}$",
+            "type": "string"
+          },
+          "extractor_version": {
+            "type": "string"
+          },
+          "language_evidence": {
+            "type": "string"
+          },
+          "language_tag": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "method": {
+            "type": "string"
+          },
+          "schema_version": {
+            "minimum": 1,
+            "type": "integer"
+          },
+          "source_asset_id": {
+            "pattern": "^sat_[0-9a-f]{24}$",
+            "type": "string"
+          },
+          "span_id": {
+            "type": "string"
+          },
+          "start_ms": {
+            "minimum": 0,
+            "type": [
+              "integer",
+              "null"
+            ]
+          },
+          "text_sha256": {
+            "pattern": "^[0-9a-f]{64}$",
+            "type": "string"
+          },
+          "transformation_class": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "extract_id",
+          "source_asset_id",
+          "schema_version",
+          "method",
+          "language_tag",
+          "language_evidence",
+          "cue_id",
+          "span_id",
+          "start_ms",
+          "end_ms",
+          "exact_text",
+          "text_sha256",
+          "transformation_class",
+          "extractor_version",
+          "created_at"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "legacy_lineage": {
+      "description": "Explicit legacy or ambiguous lineage. Empty until a bounded legacy projection is introduced; missing immutable rows are never called exact.",
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "hook_instance_id": {
+            "pattern": "^hki_[0-9a-f]{24}$",
+            "type": "string"
+          },
+          "lineage_quality": {
+            "const": "legacy_ambiguous",
+            "type": "string"
+          },
+          "reason": {
+            "const": "source_lineage_not_recorded",
+            "type": "string"
+          }
+        },
+        "required": [
+          "hook_instance_id",
+          "lineage_quality",
+          "reason"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "source_assets": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "actual_platform": {
+            "enum": [
+              "instagram",
+              "tiktok",
+              "youtube"
+            ],
+            "type": "string"
+          },
+          "author_handle": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "author_id": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "canonical_url": {
+            "format": "uri",
+            "type": "string"
+          },
+          "content_sha256": {
+            "pattern": "^[0-9a-f]{64}$",
+            "type": "string"
+          },
+          "created_at": {
+            "format": "date-time",
+            "type": "string"
+          },
+          "engagement": {
+            "type": "object"
+          },
+          "engagement_horizon": {
+            "type": "string"
+          },
+          "field_provenance": {
+            "type": "object"
+          },
+          "observed_at": {
+            "format": "date-time",
+            "type": "string"
+          },
+          "platform_media_id": {
+            "type": "string"
+          },
+          "schema_version": {
+            "minimum": 1,
+            "type": "integer"
+          },
+          "source_asset_id": {
+            "pattern": "^sat_[0-9a-f]{24}$",
+            "type": "string"
+          },
+          "source_surface": {
+            "type": "string"
+          },
+          "vendor_path": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "source_asset_id",
+          "schema_version",
+          "actual_platform",
+          "platform_media_id",
+          "canonical_url",
+          "author_id",
+          "author_handle",
+          "source_surface",
+          "vendor_path",
+          "observed_at",
+          "engagement",
+          "engagement_horizon",
+          "field_provenance",
+          "content_sha256",
+          "created_at"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "source_assets",
+    "extracts",
+    "evidence_edges",
+    "legacy_lineage",
+    "corrupt_fields"
+  ],
+  "type": "object"
+}

Changed21 schema fields changedAug 10, 2026

changedInput schema / properties / key_prefix / description

Previous value: -"Narrow the LEDGER to charges made with ONE api key, identified by the 12-char prefix from list_keys. `hooks` and `outcomes` are always the full set and are NOT narrowed by this. Omit for every key."New value: +"Narrow the LEDGER to charges made with ONE api key, identified by the 12-char prefix from list_keys. `hooks`, `hook_instances`, `hook_lineage`, `outcomes`, `jobs`, and `creator_profiles` are always the full set and are NOT narrowed by this. Omit for every key."

changedOutput schema / description

Previous value: -"Everything this account owns, in one unbounded JSON body. Free."New value: +"The account's usage-ledger, hook, outcome, retained-job, and creator-profile categories in one unbounded JSON body."

changedOutput schema / properties / account_id / description

Previous value: -"Your account id."New value: +"The exporting account id."

changedOutput schema / properties / account_id / type

Previous value: -[
-  "string",
-  "null"
-]New value: +"string"

addedOutput schema / properties / corrupt_fields

Added value: +{
+  "description": "Bounded markers for retained event, hook, or outcome JSON fields that could not be decoded safely. Raw malformed values and row identifiers are not echoed.",
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "category": {
+        "enum": [
+          "event",
+          "hook",
+          "hook_instance",
+          "hook_lineage",
+          "outcome"
+        ],
+        "type": "string"
+      },
+      "field": {
+        "enum": [
+          "governance",
+          "lineage",
+          "metadata",
+          "projection",
+          "score_json",
+          "tags_json"
+        ],
+        "type": "string"
+      },
+      "row_index": {
+        "minimum": 0,
+        "type": "integer"
+      }
+    },
+    "required": [
+      "category",
+      "row_index",
+      "field"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

changedOutput schema / properties / count / description

Previous value: -"How many ledger rows `events` carries."New value: +"Number of usage-ledger rows in events after event filters."

changedOutput schema / properties / count / type

Previous value: -[
-  "number",
-  "null"
-]New value: +"integer"

addedOutput schema / properties / creator_profiles

Added value: +{
+  "additionalProperties": false,
+  "description": "Every retained creator-profile version and consent event, plus bounded retraction markers for profiles whose direct declarations were erased.",
+  "properties": {
+    "consent_events": {
+      "items": {
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "corrupt_fields": {
+      "description": "Bounded markers for retained profile fields that could not be safely decoded. Raw malformed values and unknown keys are not echoed.",
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "category": {
+            "type": "string"
+          },
+          "profile_id": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "version": {
+            "type": [
+              "integer",
+              "null"
+            ]
+          }
+        },
+        "required": [
+          "category",
+          "profile_id",
+          "version"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "profiles": {
+      "items": {
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "retractions": {
+      "items": {
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "profiles",
+    "consent_events",
+    "retractions",
+    "corrupt_fields"
+  ],
+  "type": "object"
+}

changedOutput schema / properties / email / description

Previous value: -"Contact address given at signup, MASKED (z***@d***.com) unless the calling key has the admin scope. Null when none was given."New value: +"Contact email in full for an admin-scoped key and masked for a read-only key."

changedOutput schema / properties / events / description

Previous value: -"The FULL charge ledger, oldest first, narrowed by tag/key_prefix. Each {id, created_at, operation, credits_delta, balance_after, request_id, key_prefix, metadata}. This is the superset of the REST csv export."New value: +"Usage-ledger rows, oldest first, narrowed by event filters."

addedOutput schema / properties / events / items
```
Added value: +{
+  "type": "object"
+}
```

changedOutput schema / properties / events / type

Previous value: -[
-  "array",
-  "null"
-]New value: +"array"

addedOutput schema / properties / hook_instances

Added value: +{
+  "description": "Every immutable served-hook occurrence currently retained, including non-prose profile/version lineage when one was used. Unreferenced instances follow the hook TTL; every retained instance for a hook with any outcome remains so historical ambiguity cannot become false exactness.",
+  "items": {
+    "type": "object"
+  },
+  "type": "array"
+}

addedOutput schema / properties / hook_lineage

Added value: +{
+  "description": "Non-prose per-hook minimum occurrence counts retained until account deletion so expired or rolling-version rows cannot become falsely exact.",
+  "items": {
+    "additionalProperties": false,
+    "description": "A non-prose lower bound on paid generate/batch occurrences for one text-derived hook id. A legacy marker means pre-B2 multiplicity may be higher than the bound.",
+    "oneOf": [
+      {
+        "allOf": [
+          {
+            "if": {
+              "properties": {
+                "legacy_preexisting": {
+                  "const": true
+                }
+              },
+              "required": [
+                "legacy_preexisting"
+              ]
+            },
+            "then": {
+              "properties": {
+                "minimum_occurrence_count": {
+                  "minimum": 2
+                }
+              }
+            }
+          }
+        ],
+        "properties": {
+          "hook_id": {
+            "type": "string"
+          },
+          "legacy_preexisting": {
+            "type": "boolean"
+          },
+          "minimum_occurrence_count": {
+            "minimum": 1,
+            "type": "integer"
+          }
+        }
+      },
+      {
+        "properties": {
+          "hook_id": {
+            "type": "null"
+          },
+          "legacy_preexisting": {
+            "type": "null"
+          },
+          "minimum_occurrence_count": {
+            "type": "null"
+          }
+        }
+      }
+    ],
+    "properties": {
+      "hook_id": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "legacy_preexisting": {
+        "type": [
+          "boolean",
+          "null"
+        ]
+      },
+      "minimum_occurrence_count": {
+        "minimum": 1,
+        "type": [
+          "integer",
+          "null"
+        ]
+      }
+    },
+    "required": [
+      "hook_id",
+      "minimum_occurrence_count",
+      "legacy_preexisting"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

changedOutput schema / properties / hooks / description

Previous value: -"EVERY hook this account bought: {hook_id, request_id, topic, mode, platform, text, archetype, claim_type, score_total, score, contains_placeholder_stat, prompt_version, tags, created_at}. NOT narrowed by tag/key_prefix."New value: +"Every currently retained hook, not narrowed by event filters."

addedOutput schema / properties / hooks / items
```
Added value: +{
+  "type": "object"
+}
```

changedOutput schema / properties / hooks / type

Previous value: -[
-  "array",
-  "null"
-]New value: +"array"

addedOutput schema / properties / jobs

Added value: +{
+  "description": "Every currently retained async job, including exact commission snapshots, including schema-v2 capture-only intent when supplied, bounded request metadata, results, errors, and corruption markers. Rolling v1 execution views and worker charge identities are not presented as the accepted snapshot.",
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "commission": {
+        "type": [
+          "object",
+          "null"
+        ]
+      },
+      "commission_redacted": {
+        "description": "Bounded receipt that the exact commission snapshot was erased after creator-profile deletion. Deleted declarations are never substituted from a compatibility projection.",
+        "type": [
+          "object",
+          "null"
+        ]
+      },
+      "commissions": {
+        "items": {
+          "type": "object"
+        },
+        "type": [
+          "array",
+          "null"
+        ]
+      },
+      "corrupt_fields": {
+        "description": "Names retained fields that could not be safely decoded or projected. Their raw values are not echoed and the remaining account export still succeeds.",
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "created_at": {
+        "type": "string"
+      },
+      "creator_profile_refs": {
+        "description": "Ordered non-prose profile/version references retained for the job.",
+        "items": {
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "error": {
+        "type": [
+          "object",
+          "null"
+        ]
+      },
+      "finished_at": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "job_id": {
+        "type": "string"
+      },
+      "legacy_request": {
+        "type": [
+          "object",
+          "null"
+        ]
+      },
+      "operation": {
+        "type": "string"
+      },
+      "progress_pct": {
+        "type": [
+          "integer",
+          "null"
+        ]
+      },
+      "request_id": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "request_metadata": {
+        "additionalProperties": false,
+        "properties": {
+          "tags": {
+            "items": {
+              "type": "string"
+            },
+            "type": [
+              "array",
+              "null"
+            ]
+          }
+        },
+        "required": [
+          "tags"
+        ],
+        "type": "object"
+      },
+      "result": {
+        "type": [
+          "object",
+          "null"
+        ]
+      },
+      "stage": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "started_at": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "status": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "job_id",
+      "operation",
+      "status",
+      "stage",
+      "progress_pct",
+      "created_at",
+      "started_at",
+      "finished_at",
+      "request_id",
+      "commission",
+      "commissions",
+      "legacy_request",
+      "request_metadata",
+      "creator_profile_refs",
+      "commission_redacted",
+      "result",
+      "error",
+      "corrupt_fields"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

changedOutput schema / properties / outcomes / description

Previous value: -"EVERY outcome this account reported, each with the hook snapshot taken at report time. NOT narrowed by tag/key_prefix."New value: +"Every retained outcome, not narrowed by event filters."

addedOutput schema / properties / outcomes / items
```
Added value: +{
+  "type": "object"
+}
```

changedOutput schema / properties / outcomes / type

Previous value: -[
-  "array",
-  "null"
-]New value: +"array"

AddedAug 2, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses many non-obvious behaviors—unbounded output, email masking without admin scope, filters only narrow ledger events while other categories remain complete, and error conditions. Annotations only mark readOnlyHint, so this description carries the burden and exceeds it.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but information-dense; every sentence delivers a distinct caveat or clarification. It opens with the primary action and front-loads key facts (free, before delete_account) before detailed return categories. Slight redundancy between the first sentence's data list and later 'Returns...' list, but not enough to be wasteful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a high-complexity export tool with optional filters and a rich result set, the description covers behavior, scoping, auth, errors, and return composition. Since an output schema is present, return-value details are bonus; the operational caveats are the critical missing context and are included.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema already describes tag/key_prefix fully (100% coverage). Description adds critical cross-parameter semantics: 'Filters narrow ledger events only; all retained data categories stay complete,' which clarifies that key_prefix/tag do not limit hooks, jobs, profiles, etc. It also notes error cases tied to auth.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description opens with specific verb 'Export' and enumerates exact data categories (ledger, hooks, instances, lineage, outcomes, profiles, retained jobs). It distinguishes this from lighter paged reads by warning 'UNBOUNDED: prefer paged reads on big accounts' and by tying it to the pre-delete_account snapshot use case.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

States clear usage conditions: free, run before delete_account, not suitable for large accounts ('prefer paged reads'). It does not name specific sibling alternatives but gives enough contextual guidance to choose export vs paged reads.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All VHGENGINE tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?