Agent Utilisation

1. Overview

The Usage & Analytics APIs offer a suite of endpoints designed to provide detailed data on your Formi integration. These tools enable you to programmatically access credit balances, review historical usage for cost analysis, and drill down into the performance metrics of individual interactions and AI models (LLM, TTS). This empowers you to build custom dashboards, manage budgets effectively, and gain deep insights into your operational efficiency.

2. Common Use Cases & Benefits

Financial & Cost Management

Track real-time credit balances for all agents within an outlet.

Analyze historical credit consumption and recharge patterns for budgeting and forecasting.

Programmatically manage agent credits, including adding, updating, or clearing balances (Admin).

Performance & Utilisation Analytics

Retrieve detailed performance breakdowns for specific AI models (CONVERSATION, TRANSITION, TTS) to understand costs and latency.

Aggregate usage data by OUTLET or AGENT to identify high-performing agents or costly interaction flows.

Drill down into a single interaction's complete metadata for granular debugging and analysis.

System Integration & Automation

Feed usage data into internal financial dashboards or business intelligence (BI) tools.

Build automated alerting systems to notify administrators of low credit balances.

3. Expected Response / Response Handling

Success Condition: All successful requests will return an HTTP 200 OK status code. The response body will be a JSON object with a top-level success field set to true.

Failure Condition: Client-side errors (e.g., invalid parameters, authentication failure) will result in a 4xx status code (e.g., 400 Bad Request, 401 Unauthorized). Server-side errors will result in a 5xx status code. The response body will contain a success: false field and a descriptive message.

4. Example Flow / Scenario Walkthrough

Scenario: A manager wants to check the monthly credit usage for their main call center outlet.

5. Developer Notes & Best Practices

Idempotency: All GET endpoints are idempotent and safe to retry. The POST /credits/set endpoint is not idempotent when using mode: "add".

Caching: For analytics dashboards, it is highly recommended to cache the results of usage queries to improve performance and avoid rate limits. A cache duration of 1 to 24 hours is often suitable.

Date Ranges: When querying by date, the end_date parameter is inclusive.

6. Security Considerations

JWT Security: Your outlet-specific JWT is a sensitive credential. It should be stored securely on your backend and never exposed in client-side code (e.g., in a web browser).

HTTPS: All API requests must be made over https:// to ensure data is encrypted in transit.

1. Overview#

2. Common Use Cases & Benefits#

3. Expected Response / Response Handling#

4. Example Flow / Scenario Walkthrough#