Using Ganivra
User manual
Connect customer revenue, understand your costs, and keep your workspace configuration under control.
Choose a task below. Product links preserve your selected workspace; access permissions still apply.
Correct usage and inspect pricing history
- An administrator can submit a complete corrected event through POST /v1/events/{event_id}/corrections or the SDK events.correct helper. Preserve event_id, supply the actual occurrence timestamp, and include a stable request UUID and a specific reason. This is an API workflow, not an edit button in the dashboard.
- The current event is updated without adding a call. Original facts and before/after evidence remain available through GET /v1/events/{event_id}/history or events.history with a signed-in user token. Original ingestion retries cannot undo a correction. Changed payloads under an existing ingestion ID return HTTP 409.
- Historical repricing now records before/after pricing in the same history. Evidence begins at deployment; earlier overwritten prices cannot be reconstructed. Live reporting changes, but confirmed revenue entries, saved statements and external invoices need separate review.
- Revenue imports are atomic: either the whole request commits or none of it does. Investigate a conflict before retrying; preserve IDs and payloads when retrying an uncertain delivery.
Use the Python SDK for integration and administration
- Install SDK 0.6.1 for the explicit REST client and current helpers. Automatic capture supports synchronous, non-streaming OpenAI Responses and Claude Messages sync, async and streaming with the Anthropic extra. Gemini and unsupported APIs require explicit usage submission.
- Use Client(api_key=...) for model/MCP events, revenue entries, transactions and delivery costs. Supply stable IDs and real occurrence timestamps. Keep delivery costs on their separate endpoint and avoid reporting the same charge twice.
- Use Client(access_token=..., workspace_id=...) for reports and administration. Supply a signed-in user token or a callback returning the refreshed token, never a service-role secret. Ingestion keys cannot administer plans or read workspace data; existing role checks remain in force.
- Manage pricing plans, customer assignments and historical effective dates through pricing_plans and customer_plans. Extend plan dates before an earlier assignment when necessary. Use economics for contract rates, reconciliation and repricing. Date changes affect live plan-based reporting, not original usage or saved statements.
- Use delivery_costs for investigations, evidence, invoice policies and snapshots; reports for costs, exports and allocation rules; audit for administrative history; bills, budgets, workspaces and account for their management operations. Use value.list and value.import_assessment for customer value evidence. The integration walkthrough lists the methods and examples.
- Pass JSON bodies through payload and query filters through params. Export methods return bytes, pagination is explicit, and HTTP failures expose APIError.status_code, body, headers and retry_after when provided. Writes are not automatically retried: reuse stable IDs for ingestion and inspect state before repeating non-idempotent changes.
Cover historical executions with the correct plan dates
- Open Settings → Customer pricing → Review effective dates and historical coverage. Expand the customer assignment and set the actual effective start and optional end. All inputs are UTC; the end is exclusive.
- If the pricing plan itself starts too late, expand Plan availability dates and extend it first. Plan date changes affect every customer using that plan. Assignment periods cannot overlap; adjust an adjacent assignment first when needed.
- Save and refresh Customer economics. Live plan-based revenue is recalculated, including monthly subscription allocation. Usage records, confirmed revenue entries, and saved statements are not rewritten. Administrative history records the date change.
- The missing-revenue warning shows the execution timestamp and applicable date ranges. Use Inspect execution to verify the historical action before changing its coverage. Explicit event plan keys still take precedence over manual assignments.
Explain changes in customer economics
- Open Why did economics change? from Dashboard or Delivery costs. Choose the current period and optionally a customer and workflow. The comparison uses the immediately preceding equal-length period; end dates are exclusive.
- Review revenue, recorded delivery cost, and contribution differences. Category deltas add up to recorded cost change. The separate model/tool decomposition splits its cost change into execution volume at the old average cost and the remaining average-cost effect. Do not add that decomposition to category deltas again.
- Inspect changed token usage, errors and model lists, affected customers/workflows, and representative records. Administrative changes are workspace-wide context, with actors and snapshots; timing does not establish causation.
- Follow execution and cost-evidence links. Invoice allocations include the source bill. Missing revenue, small samples and unpriced costs are explicit limitations. Periods use current stored configuration, not historical as-of pricing; saved delivery statements preserve prior reports.
Review recorded delivery costs
- Open Delivery costs for a combined view of model/tool telemetry, external service events, and imported delivery bills. Select a period, customer, workflow, agent, feature, or execution. These are recorded costs, not a guarantee that all costs were captured.
- Record telephony, speech, OCR, search, retrieval, compute, storage, network, or external-tool events through the SDK/API or event import. Supply a stable provider event ID, occurrence timestamp, source reference, attribution, and either a USD amount or quantity with a versioned unit rate. Do not report the same charge through model/MCP telemetry and delivery events.
- Match imported invoice lines to existing delivery-event IDs to verify costs without adding the bill again. Provider and service period must match. Differences stay visible; record an explicit signed correction to adjust costs. Matching by itself never changes usage facts.
- For genuinely additional shared costs, allocate an imported bill using customer percentages and a documented basis. Percentages apply to the bill's workspace share, cannot exceed 100%, and the remainder stays unallocated. These allocations are estimates, even when based on measured usage.
- Export evidence or save a workspace statement. Saved statements preserve the original numbers; late events and corrections change the live report only. Save a new statement and compare evidence when restating a period. This is not an invoice or an accounting-period lock.
- Agent views do not allocate revenue. Customer contribution can exclude unallocated costs. Model-only dashboards and budgets retain their existing scope; use Delivery costs for the expanded report.
Choose the right workspace
- Use the workspace selector before inspecting data or changing configuration. Your main workspace is labeled with its actual name followed by (Primary). Additional workspaces have their own events, keys, pricing plans and customer assignments.
- The API key determines where usage lands. Metadata cannot redirect it. If recent events are missing, compare the deployed key’s workspace with the selected workspace, then clear filters and refresh.
- Additional workspaces linked to your primary workspace share its Ganivra plan allowance. Unrelated accounts are not combined, even if their workspace names match.
Verify your first execution
- Open the integration guide and choose outbound calling, an agent workflow, or document processing. Supply customer_id, application, feature and workflow consistently across the model and MCP steps of one business action.
- Use one execution_id for the action and distinct event/step IDs for actual calls. Redelivering telemetry must preserve event_id. A real model retry is another call and needs its own event ID.
- Open Executions, refresh, and inspect the customer, quantities, model/tool costs and status. A 202 response confirms API acceptance, not that every attribution or pricing field is present. Unknown model pricing needs a rate before contribution is reliable.
Configure customer plans and assignments
- In Settings → Define customer pricing, enter a name, a stable key such as starter or growth, a pricing model and its rates. Choose subscription, per execution, per token, credit/unit, or hybrid. This is what your customers pay you, separate from your Ganivra subscription.
- Automatic mapping: send attributes.customer_id plus attributes.plan_key. A matching effective plan in the same workspace is used without a manual assignment. Rates are configured in Ganivra; the event sends the key and usage.
- Manual mapping remains available: use Assign a customer (optional), enter the exact customer ID and choose the plan. Events may omit plan_key. An explicit key takes precedence; an invalid key produces a warning instead of silently using the assignment.
- Credit/unit plans also need actual execution-level quantity in the configured unit_attribute, such as credits or pages_processed. The maximum quantity across steps is used, not their sum. Send the final total when known; zero is a valid quantity.
- To change a customer’s plan, send the new configured key on future executions or change its assignment. Earlier events retain their supplied keys. Stored keys are not immutable rate snapshots: updating an existing plan can change recalculated history. Use a distinct key for a new rate version when preserving the old rate matters.
- The Settings form creates plans and assignments; it does not offer a full historical plan editor or effective-date controls. Use the documented pricing-plan/customer-plan API for explicit effective dates and existing-key updates. Creating a plan with an existing key updates that plan, so review historical impact before submitting.
Resolve missing revenue
- Customer economics → Connect missing revenue lists affected customers, plan keys and execution counts. Usage and costs remain stored while setup is incomplete.
- Plan not configured: create the exact key in the receiving workspace, with dates covering the events, then refresh. Existing usage can be calculated without resending events. No rates are inferred from a name like growth.
- Plan or assignment date mismatch: review the occurrence timestamp and effective dates. Effective periods include their start and exclude their end.
- Missing or invalid units: send the configured quantity as a finite, non-negative number. Resending the same event ID with changed attributes does not amend the stored event; investigate the affected execution before correcting the integration.
- Missing customer or conflicting attribution: use the paying tenant’s stable ID, and one customer and plan across an execution. Unsupported plan currency requires a USD plan or converted revenue reporting.
- Unknown revenue means no applicable revenue was found, not a confirmed zero. Partial revenue means some executions remain unresolved; contribution stays unknown in the customer economics table. Confirmed revenue takes precedence over applicable plan estimates.
Review customer and workflow margins
- The dashboard opens on Customer economics. Select a period and customer, then inspect workflow and feature rows. View executions opens the underlying calls with the same workspace, period and filters. Use Clear filters and Refresh data to return to a fresh view.
- Contribution after recorded costs = connected revenue minus the recorded costs included in the view. Contribution margin = contribution divided by revenue. These are not total company profit or necessarily complete gross margin: missing or unallocated delivery costs can materially change the result.
- Revenue basis distinguishes reported revenue, calculated plan revenue, allocated subscription revenue and refunds. Workflow revenue may be allocated across executions; it is not necessarily a direct payment for that workflow.
- Inspect coverage before interpreting a positive margin. Recorded calls priced means the calls received have rates; it does not prove every call, retrieval, telephony or compute cost was captured. Unattributed rows need customer/feature/workflow context.
- The margin target defaults to 60% and can be changed in the dashboard. It is a comparison threshold, not the calculated margin, price, or spending cap. It resets on reload.
- Margin outlook estimates month-end economics from recent recorded usage where coverage supports a forecast. Insufficient data is an expected result for sparse or incomplete history. Forecasts are assumptions, not guarantees; they exclude unallocated delivery costs.
Connect payments, bills and reconciliation
- Import billing actuals in Settings or report confirmed purchases, subscription payments, credit purchases and refunds through the Transactions API. Use the same customer ID, and execution_id when a payment belongs to one result. These records report money movement; Ganivra does not charge the customer.
- For subscriptions, send transaction_type: subscription_payment for each confirmed payment or renewal. Use a unique payment or paid invoice ID as external_id, not the recurring subscription ID. Omit execution_id for a general subscription.
- For a one-time purchase, send transaction_type: one_time_purchase with the confirmed amount and currency. Include the original execution_id when the payment belongs to one AI result. Use the server-side workspace key and reuse external_id on retries; occurred_at should remain the actual payment time.
- In Bills, preview a supported CSV or add manual costs. Additional delivery costs can contribute to workspace economics; AI invoice references avoid adding a second copy of telemetry cost. Shared bills are not automatically allocated to customer/feature margins.
- Use Reconcile a provider invoice in Settings or Cost reports to compare recorded provider totals with estimated costs for the same period. Investigate variance, unpriced usage and incomplete coverage. Provider invoice synchronization and line-by-line matching are not automatic.
- Cost reports provide exportable evidence. Treat reconciled/fully priced status as scoped to supplied records, not proof of complete financial accounting.
Review your Ganivra plan consumption
- In Settings → Plan consumption, the subscription owner sees one shared allowance across the primary workspace and its linked additional workspaces, with a workspace breakdown.
- Each accepted model call and each MCP call counts once. One execution may contain many calls. Dashboard filters and key rotation do not change consumption. Duplicate event IDs within a workspace are not counted again; the same ID in another workspace is separate.
- Consumption uses server receipt time and the configured billing period. Economics uses event occurrence time, so delayed events can appear in different periods in these two views. Sample events also count.
- Paid periods must be configured; they do not renew automatically. Without a subscription record, the account uses the trial rules. Delegated access to a client workspace does not expose account-wide usage. Usage tracking does not enable automated charging or hard limits.
Manage budgets and review alerts
- Open Budgets and choose a workspace-wide budget or a supported dimension such as customer, feature or workflow. Set an accountable owner, USD amount, period and thresholds. Defaults are 80% warning and 100% critical.
- Review unpriced usage as well as known spend. Owners/admins can record Acknowledge, Investigate, Action required or Approve exception with a reason. An exception records a decision; it does not increase the budget or suppress future alerts.
- Budget dates and thresholds are fixed after creation; archive and replace a budget to change them. History remains available. Overlapping budgets measure overlapping costs and should not be summed.
- Use Refresh budgets to evaluate current conditions. These are in-app review controls, not provider spending caps or email/Slack notifications. Viewers can inspect history but cannot perform administrative actions.
Read administrative history
- Open Administrative history to investigate configuration changes: who created or revoked a key, changed customer pricing, modified access, or exported records. It complements Executions, which records what the application did.
- Rows use readable actions and current workspace member emails where available. A user ID is the fallback. View details shows before/after changes and record IDs; Technical evidence exposes the stored JSON snapshot.
- Filter by change type, user ID and UTC dates. Before (UTC) is an exclusive end boundary. Clear filters resets the view. Export filtered CSV downloads matching records within the export limit; exports are themselves recorded.
- History begins when auditing was enabled; earlier actions are not reconstructed. A key rotation can produce separate revoked-key and created-key entries. These entries do not prove the replacement key was deployed or that telemetry arrived.
A practical weekly review
- Check the selected workspace and refresh. Resolve missing customer IDs, plan warnings and unpriced calls first.
- Review customers with unknown or negative contribution; inspect their workflow/feature costs and underlying executions. Compare equivalent periods before changing pricing or implementation.
- Review budget alerts and record decisions. Compare provider invoices with telemetry, and confirm actual revenue is current.
- Review shared plan consumption and administrative changes. Use Value measurement separately when you want to assess customer outcomes or ROI; its assumptions are not automatic proof of realized value.