Usage

class Usage(session_kwargs, client, return_type='raw')

Civis API /usage endpoint:

import civis
client = civis.APIClient()
# Call client.usage.<method>(<arguments>) to make a request, e.g.:
client.usage.list_matching(...)

Methods

`get_llm`(id)	Get an individual usage statistic for a given organization
`get_llm_organization_summary`(org_id, *[, ...])	Get summarized usage statistics for a given organization
`list_llm`(*[, org_id, start_date, end_date])	Get a list of usage statistics for a given organization
`list_llm_organization_summary`(org_id, *[, ...])	Get summarized usage statistics for a given organization
`list_matching`(*[, org_id, task, start_date, ...])	Get usage statistics for a given organization

get_llm(id: int) → Response

Get an individual usage statistic for a given organization

API URL: GET /usage/llm/{id}

Parameters:

idint: The ID of the usage statistic to get.

Returns:

civis.Response

idint
The ID of the usage statistic to get.
run_idint
The ID of the run which contributed this usage.
job_idint
The ID of the job which contributed this usage.
user_idint
The ID of the user who contributed this usage.
organization_idint
The organization of the user who contributed this usage.
run_created_atstr (date-time)
When the run was created at.
run_timeint
The duration of the run in seconds.
creditsfloat (float)
The number of credits used.
input_tokensint
The number of tokens input to the run.
output_tokensint
The number of tokens output from the run.
model_idstr
The ID of the LLM model used.

get_llm_organization_summary(org_id: int, *, start_date: str = None, end_date: str = None) → Response

Get summarized usage statistics for a given organization

API URL: GET /usage/llm/organization/{org_id}/summary

Parameters:

org_idint: The ID of the organization to get usage statistics for.
start_datestr, optional: The start date of the range to get usage statistics for.”“Defaults to the start of the current month if neither start_date nor end_date is specified.
end_datestr, optional: The end date of the range to get usage statistics for.”“Defaults to the end of the current day if neither start_date nor end_date is specified.

Returns:

civis.Response

creditsfloat (float)
The number of credits used.
organization_idint
The organization for which LLM usage statistics are summarized.

list_llm(*, org_id: int = None, start_date: str = None, end_date: str = None) → ListResponse

Get a list of usage statistics for a given organization

API URL: GET /usage/llm

Parameters:

org_idint, optional: The ID of the organization to get usage statistics for.
start_datestr, optional: The start date of the range to get usage statistics for.”“Defaults to the start of the current month if neither start_date nor end_date is specified.
end_datestr, optional: The end date of the range to get usage statistics for.”“Defaults to the end of the current day if neither start_date nor end_date is specified.

Returns:

civis.ListResponse

idint
The ID of the usage statistic to get.
run_idint
The ID of the run which contributed this usage.
job_idint
The ID of the job which contributed this usage.
user_idint
The ID of the user who contributed this usage.
organization_idint
The organization of the user who contributed this usage.
run_created_atstr (date-time)
When the run was created at.
run_timeint
The duration of the run in seconds.
creditsfloat (float)
The number of credits used.
input_tokensint
The number of tokens input to the run.
output_tokensint
The number of tokens output from the run.
model_idstr
The ID of the LLM model used.

list_llm_organization_summary(org_id: int, *, start_date: str = None, end_date: str = None) → ListResponse

Get summarized usage statistics for a given organization

API URL: GET /usage/llm/organization/{org_id}/summary

Warning

The method name <client>.usage.list_llm_organization_summary is deprecated and will be removed at civis-python v3.0.0 (no release timeline yet). Please switch to <client>.usage.get_llm_organization_summary for the same method.

Parameters:

org_idint: The ID of the organization to get usage statistics for.
start_datestr, optional: The start date of the range to get usage statistics for.”“Defaults to the start of the current month if neither start_date nor end_date is specified.
end_datestr, optional: The end date of the range to get usage statistics for.”“Defaults to the end of the current day if neither start_date nor end_date is specified.

Returns:

civis.Response

creditsfloat (float)
The number of credits used.
organization_idint
The organization for which LLM usage statistics are summarized.

list_matching(*, org_id: int = None, task: str = None, start_date: str = None, end_date: str = None) → ListResponse

Get usage statistics for a given organization

API URL: GET /usage/matching

Parameters:

org_idint, optional: The ID of the organization to get usage statistics for.
taskstr, optional: The type of matching job contributing to this usage. One of [“IDR”, “CDM”].
start_datestr, optional: The start date of the range to get usage statistics for.
end_datestr, optional: The end date of the range to get usage statistics for.

Returns:

civis.ListResponse

run_idint
The ID of the run which contributed this usage.
job_idint
The ID of the job which contributed this usage.
user_idint
The ID of the user who contributed this usage.
organization_idint
The organization of the user who contributed this usage.
run_created_atstr (date-time)
When the run was created at.
run_timeint
The duration of the run in seconds.
num_recordsint
The number of records matched by the run.
taskstr
The type of matching job contributing to this usage. One of [“IDR”, “CDM”].