Overview

This document provides detailed reference information for the KPI-related resources in the Pay-i Python SDK. For usage examples and best practices, see the Python SDK KPIs guide.

The Pay-i Python SDK provides two distinct KPI resources:

Definition-level KPIs: client.use_cases.definitions.kpis - Used to define what KPIs exist for a use case type
Instance-level KPI values: client.use_cases.kpis - Used to record and manage actual KPI values for specific use case instances

This two-tiered approach allows for standardized KPI definitions across all instances of a use case type, while enabling instance-specific measurements.

KPI Definitions API

KPI definitions establish what metrics will be tracked for a given use case type. These are created once per use case type and serve as templates for recording values.

Method Reference

Method	Description	Return Type	REST API Endpoint
`create()`	Creates a new KPI definition	`KpiDefinitionResponse`	Create KPI Definition
`retrieve()`	Gets a specific KPI definition	`KpiDefinitionResponse`	Get KPI Definition
`list()`	Lists all KPI definitions for a use case	`SyncCursorPage[KpiDefinitionResponse]`	List KPI Definitions
`update()`	Updates an existing KPI definition	`KpiDefinitionResponse`	Update KPI Definition
`delete()`	Deletes a KPI definition	`DefaultResponse`	Delete KPI Definition

Method Details

create() KPI Definition

client.use_cases.definitions.kpis.create(
    use_case_name: str,
    kpi_name: str,
    description: str,
    kpi_type: Literal["boolean", "number", "percentage", "likert5", "likert7", "likert10"],
    goal: float
) -> KpiDefinitionResponse

Creates a new KPI definition for a specific use case type.

Parameters:

use_case_name (required): The name of the use case type this KPI belongs to
kpi_name (required): Unique identifier for this KPI within the use case
description (required): Human-readable explanation of what this KPI measures
kpi_type (required): The type of measurement this KPI represents
goal (required): Target value for this KPI

Returns: A KpiDefinitionResponse object containing the created KPI definition details.

Example:

# Create a Customer Satisfaction KPI for the Chat-Bot use case type
response = client.use_cases.definitions.kpis.create(
    use_case_name="Chat-Bot",
    kpi_name="Customer Satisfaction",
    description="User rating of chat quality",
    kpi_type="likert5",
    goal=4.0
)

retrieve() KPI Definition

client.use_cases.definitions.kpis.retrieve(
    use_case_name: str,
    kpi_name: str
) -> KpiDefinitionResponse

Retrieves a specific KPI definition.

Parameters:

use_case_name (required): The use case type this KPI belongs to
kpi_name (required): The name of the KPI to retrieve

Returns: A KpiDefinitionResponse object containing the KPI definition details.

Example:

# Retrieve the Customer Satisfaction KPI definition
response = client.use_cases.definitions.kpis.retrieve(
    use_case_name="Chat-Bot",
    kpi_name="Customer Satisfaction"
)

list() KPI Definitions

client.use_cases.definitions.kpis.list(
    use_case_name: str,
    cursor: Optional[str] = None,
    limit: Optional[int] = None,
    sort_ascending: Optional[bool] = None
) -> SyncCursorPage[KpiDefinitionResponse]

Lists all KPI definitions for a specific use case type.

Parameters:

use_case_name (required): The use case type to list KPI definitions for
cursor: Pagination cursor for fetching the next page of results
limit: Maximum number of items per page
sort_ascending: Sort order (true for ascending, false for descending)

Returns: A list-like object containing KPI definitions.

Example:

# List all KPI definitions for the Chat-Bot use case type
kpi_definitions = client.use_cases.definitions.kpis.list(
    use_case_name="Chat-Bot"
)

# Iterate through all KPI definitions
for kpi_def in kpi_definitions:
    print(f"KPI: {kpi_def.name}, Type: {kpi_def.kpi_type}, Goal: {kpi_def.goal}")

update() KPI Definition

client.use_cases.definitions.kpis.update(
    use_case_name: str,
    kpi_name: str,
    description: Optional[str] = None,
    goal: Optional[float] = None
) -> KpiDefinitionResponse

Updates an existing KPI definition. Note that only the description and goal can be modified after creation.

Parameters:

use_case_name (required): The use case type this KPI belongs to
kpi_name (required): The name of the KPI to update
description: New description for the KPI
goal: New goal value for the KPI

Returns: A KpiDefinitionResponse object containing the updated KPI definition.

Example:

# Update the goal for the Customer Satisfaction KPI
response = client.use_cases.definitions.kpis.update(
    use_case_name="Chat-Bot",
    kpi_name="Customer Satisfaction",
    goal=4.5
)

delete() KPI Definition

client.use_cases.definitions.kpis.delete(
    use_case_name: str,
    kpi_name: str
) -> DefaultResponse

Deletes a KPI definition.

Parameters:

use_case_name (required): The use case type this KPI belongs to
kpi_name (required): The name of the KPI to delete

Returns: A DefaultResponse object confirming deletion.

Example:

# Delete the Customer Satisfaction KPI definition
response = client.use_cases.definitions.kpis.delete(
    use_case_name="Chat-Bot",
    kpi_name="Customer Satisfaction"
)

KPI Values API

KPI values represent actual measurements recorded for specific use case instances. These are always associated with both a KPI definition (by name) and a use case instance (by ID).

Method Reference

Method	Description	Return Type	REST API Endpoint
`create()`	Records a new KPI value	`DefaultResponse`	Create KPI Value
`list()`	Lists all KPI values for a use case instance	`SyncCursorPage[KpiValueResponse]`	List KPI Values
`update()`	Updates an existing KPI value	`DefaultResponse`	Update KPI Value
`delete()`	Deletes a KPI value	`DefaultResponse`	Delete KPI Value

Method Details

create() KPI Value

client.use_cases.kpis.create(
    kpi_name: str,
    use_case_id: str,
    score: float
) -> DefaultResponse

Records a new KPI value for a specific use case instance.

Parameters:

kpi_name (required): The name of the KPI to record (must match a defined KPI for this use case type)
use_case_id (required): The ID of the use case instance to record the KPI for
score (required): The actual measurement value

Returns: A DefaultResponse object confirming the operation.

Example:

# Record a customer satisfaction score for a specific chat session
response = client.use_cases.kpis.create(
    kpi_name="Customer Satisfaction",
    use_case_id="uc_123456789",
    score=4.5
)

list() KPI Values

client.use_cases.kpis.list(
    use_case_id: str,
    kpi_name: Optional[str] = None,
    cursor: Optional[str] = None,
    limit: Optional[int] = None,
    sort_ascending: Optional[bool] = None
) -> SyncCursorPage[KpiValueResponse]

Lists all KPI values for a specific use case instance, with optional filtering by KPI name.

Parameters:

use_case_id (required): The ID of the use case instance to list KPI values for
kpi_name: Filter results to a specific KPI
cursor: Pagination cursor for fetching the next page of results
limit: Maximum number of items per page
sort_ascending: Sort order (true for ascending, false for descending)

Returns: A list-like object containing KPI values.

Example:

# List all KPI values for a specific chat session
kpi_values = client.use_cases.kpis.list(
    use_case_id="uc_123456789"
)

# Iterate through all KPI values
for kpi in kpi_values:
    print(f"KPI: {kpi.kpi_name}, Score: {kpi.score}, Type: {kpi.kpi_type}")

update() KPI Value

client.use_cases.kpis.update(
    kpi_name: str,
    use_case_id: str,
    score: float
) -> DefaultResponse

Updates the score for an existing KPI value.

Parameters:

kpi_name (required): The name of the KPI to update
use_case_id (required): The ID of the use case instance
score (required): The new measurement value

Returns: A DefaultResponse object confirming the update.

Example:

# Update a satisfaction score after additional feedback
response = client.use_cases.kpis.update(
    kpi_name="Customer Satisfaction",
    use_case_id="uc_123456789",
    score=5.0
)

delete() KPI Value

client.use_cases.kpis.delete(
    kpi_name: str,
    use_case_id: str
) -> DefaultResponse

Deletes a specific KPI value.

Parameters:

kpi_name (required): The name of the KPI value to delete
use_case_id (required): The ID of the use case instance

Returns: A DefaultResponse object confirming deletion.

Example:

# Delete an erroneously recorded KPI value
response = client.use_cases.kpis.delete(
    kpi_name="Customer Satisfaction",
    use_case_id="uc_123456789"
)

Response Types

The KPI APIs return several different response types depending on the method called:

KpiDefinitionResponse

Returned by KPI definition methods (create(), retrieve(), update()) and as items in the list() response.

KpiDefinitionResponse:
    name: str                     # KPI name/identifier
    description: str              # Human-readable description
    kpi_type: str                 # Type of measurement (boolean, number, etc.)
    goal: float                   # Target value for this KPI
    active: bool                  # Whether this KPI is currently active
    created_at: datetime          # When this KPI definition was created
    updated_at: Optional[datetime] # When this KPI definition was last updated

KpiValueResponse

Returned as items in the list() response for KPI values.

KpiValueResponse:
    kpi_name: str                 # KPI name/identifier
    score: float                  # The actual measurement value
    kpi_type: str                 # Type of measurement (boolean, number, etc.)
    create_timestamp: datetime    # When this KPI value was created
    update_timestamp: datetime    # When this KPI value was last updated

DefaultResponse

Returned by delete() methods and some other operations.

DefaultResponse:
    request_id: str               # Server-generated trace identifier
    message: Optional[str]        # Optional status message

Common Usage Patterns

Complete KPI Implementation Flow

The complete flow for implementing KPIs in your application typically involves:

Define the KPIs for your use case type (done once during application setup):

# Create KPI definitions for your use case type
client.use_cases.definitions.kpis.create(
    use_case_name="Chat-Bot",
    kpi_name="Deflection Rate",
    description="Tracks when AI resolves issues without human intervention",
    kpi_type="boolean",
    goal=0.25
)

Create use case instances as needed (each time the use case occurs):

# Create a new use case instance when a chat session begins
use_case_response = client.use_cases.create(use_case_name="Chat-Bot")
use_case_id = use_case_response.use_case_id

Record KPI values for the instances:

# Record whether the AI successfully handled the query without human intervention
client.use_cases.kpis.create(
    kpi_name="Deflection Rate",
    use_case_id=use_case_id,
    score=1.0  # True for boolean KPIs
)

Analyze KPI data through the Pay-i dashboard or by listing KPI values programmatically.

Handling Different KPI Types

Different KPI types require different score values:

boolean: 0.0 (false) or 1.0 (true)
number: Any numeric value
percentage: A value from 0.0 to 100.0
likert5: A value from 1.0 to 5.0
likert7: A value from 1.0 to 7.0
likert10: A value from 1.0 to 10.0

Example:

# Boolean KPI
client.use_cases.kpis.create(
    kpi_name="Deflection Rate",
    use_case_id=use_case_id,
    score=1.0  # True
)

# Numeric KPI
client.use_cases.kpis.create(
    kpi_name="Time Saved",
    use_case_id=use_case_id,
    score=3.5  # Minutes
)

# Likert5 KPI
client.use_cases.kpis.create(
    kpi_name="Customer Satisfaction",
    use_case_id=use_case_id,
    score=4.0  # 4 out of 5
)

Related Resources

Use Case KPIs - Core concepts of using KPIs in Pay-i
Working with KPIs - Practical guide for implementing KPIs
KPI Best Practices - Recommendations for effective KPI implementation
Pay-i API Reference: KPIs - Complete REST API documentation