Provide usage data for the given filters. Such as consumed compute units, number of assets generated, etc. Maximum time range with custom startDate and endDate is 120 days. Granularity is calculated based on the time range.
Parameters
activity_offset: Optional[float]
The offset for the activity data. Default is 0. If bad offset or empty, 0 will be returned. Must be a positive integer.
When set, points whose numeric fields are all zero are removed from usages, modelUsages, assetUsages and nsfwUsages. The parent entry (model, kind, label, usageName) is preserved with points: [] so callers still see every row. Useful on wide windows × fine granularities × many models, where the zero-fill can push the response past the 6 MB API Gateway sync limit. The bare ?dropZeroPoints form, plus any value (true, 1, yes, on, …) enables it; absent or explicit falsy literals (false, 0, no, off) disable it. Default disabled for backwards compatibility.
end_date: Optional[str]
The end date of the usage in ISO 8601 format. If not provided, use default timeRange. If provided, startDate is required.
project_ids: Optional[str]
The project ids for filtering the usage data. If not provided, use all projects. Can be one or more comma separated values.
start_date: Optional[str]
The start date of the usage in ISO 8601 format. If not provided, use default timeRange. If provided, endDate is required.
List
import os
from scenario_sdk import Scenario
client = Scenario(
api_key=os.environ.get("SCENARIO_SDK_API_KEY"), # This is the default and can be omitted
api_secret=os.environ.get("SCENARIO_SDK_API_SECRET"), # This is the default and can be omitted
)
usages = client.usages.list()
print(usages.activity){
"activity": [
{
"action": "asset",
"data": {
"assetId": "assetId",
"byokProvider": {
"id": "id",
"displayName": "displayName"
},
"collectionId": "collectionId",
"isApiKey": true,
"jobId": "jobId",
"modelId": "modelId"
},
"projectId": "projectId",
"time": "time",
"userId": "userId",
"creativeUnitsCost": 0
}
],
"assetUsages": [
{
"kind": "3d",
"points": [
{
"count": 0,
"countApiKey": 0,
"time": "time"
}
]
}
],
"consumption": [
{
"discount": 0,
"total": 0,
"userId": "userId",
"value": 0
}
],
"entities": {
"assets": [
{
"id": "id",
"kind": "3d",
"metadata": {
"type": "3d-texture"
},
"properties": {
"size": 0,
"animationFrameCount": 0,
"bitrate": 0,
"boneCount": 0,
"channels": 0,
"classification": "effect",
"codecName": "codecName",
"description": "description",
"dimensions": [
0,
0,
0
],
"duration": 0,
"faceCount": 0,
"format": "format",
"frameRate": 0,
"hasAnimations": true,
"hasNormals": true,
"hasSkeleton": true,
"hasUVs": true,
"height": 0,
"nbFrames": 0,
"sampleRate": 0,
"transcription": {
"text": "text"
},
"vertexCount": 0,
"width": 0
},
"source": "3d23d"
}
],
"collections": [
{
"id": "id",
"name": "name"
}
],
"jobs": [
{
"id": "id",
"jobType": "assets-download",
"metadata": {
"assetIds": [
"string"
],
"error": "error",
"flow": [
{
"id": "id",
"status": "failure",
"type": "custom-model",
"assets": [
{
"assetId": "assetId",
"url": "url"
}
],
"count": 0,
"dependsOn": [
"string"
],
"includeOutputsInWorkflowJob": true,
"inputs": [
{
"name": "name",
"type": "boolean",
"allowedValues": [
{}
],
"backgroundBehavior": "opaque",
"color": true,
"costImpact": true,
"default": {},
"description": "description",
"group": "group",
"hint": "hint",
"inputs": [
{
"foo": "bar"
}
],
"items": [
[
{
"name": "name",
"type": "boolean",
"allowedValues": [
{}
],
"backgroundBehavior": "opaque",
"color": true,
"costImpact": true,
"default": {},
"description": "description",
"group": "group",
"hint": "hint",
"inputs": [
{
"foo": "bar"
}
],
"kind": "3d",
"label": "label",
"maskFrom": "maskFrom",
"max": 0,
"maxDuration": 0,
"maxLength": 0,
"maxSize": 0,
"min": 0,
"minLength": 0,
"modelTypes": [
"custom"
],
"parent": true,
"placeholder": "placeholder",
"prompt": true,
"promptSpark": true,
"ref": {
"conditional": [
"string"
],
"equal": "equal",
"name": "name",
"node": "node"
},
"required": {
"always": true,
"conditionalValues": {},
"ifDefined": {},
"ifNotDefined": {}
},
"step": 1,
"value": {}
}
]
],
"kind": "3d",
"label": "label",
"maskFrom": "maskFrom",
"max": 0,
"maxDuration": 0,
"maxLength": 0,
"maxSize": 0,
"min": 0,
"minLength": 0,
"modelTypes": [
"custom"
],
"parent": true,
"placeholder": "placeholder",
"prompt": true,
"promptSpark": true,
"ref": {
"conditional": [
"string"
],
"equal": "equal",
"name": "name",
"node": "node"
},
"required": {
"always": true,
"conditionalValues": {},
"ifDefined": {},
"ifNotDefined": {}
},
"step": 1,
"value": {}
}
],
"items": [
"string"
],
"iterationIndex": 0,
"jobId": "jobId",
"logic": {
"cases": [
{
"condition": "condition",
"value": "value"
}
],
"default": "default",
"transform": "transform"
},
"logicType": "if-else",
"loopBodyNodeIds": [
"string"
],
"loopNodeId": "loopNodeId",
"modelId": "modelId",
"output": {},
"workflowId": "workflowId"
}
],
"hint": "hint",
"input": {
"foo": "bar"
},
"output": {
"foo": "bar"
},
"outputModelId": "outputModelId",
"workflowId": "workflowId",
"workflowJobId": "workflowJobId"
},
"status": "canceled"
}
],
"models": [
{
"id": "id",
"name": "name",
"shortDescription": "shortDescription"
}
],
"users": [
{
"id": "id",
"isApiKey": true,
"apiKeyId": "apiKeyId",
"apiKeyStatus": "active",
"avatar": {
"assetId": "assetId",
"url": "url"
},
"email": "email",
"fullName": "fullName"
}
]
},
"modelUsages": [
{
"modelId": "modelId",
"points": [
{
"apiKeyCost": 0,
"apiKeyDiscount": 0,
"cost": 0,
"discount": 0,
"jobs": 0,
"time": "time"
}
]
}
],
"nsfwUsages": [
{
"label": "label",
"points": [
{
"count": 0,
"countApiKey": 0,
"time": "time"
}
]
}
],
"usages": [
{
"granularity": "15m",
"points": [
{
"apiKey": "apiKey",
"time": "time",
"value": "value"
}
],
"usageName": "background-removal"
}
]
}Returns Examples
{
"activity": [
{
"action": "asset",
"data": {
"assetId": "assetId",
"byokProvider": {
"id": "id",
"displayName": "displayName"
},
"collectionId": "collectionId",
"isApiKey": true,
"jobId": "jobId",
"modelId": "modelId"
},
"projectId": "projectId",
"time": "time",
"userId": "userId",
"creativeUnitsCost": 0
}
],
"assetUsages": [
{
"kind": "3d",
"points": [
{
"count": 0,
"countApiKey": 0,
"time": "time"
}
]
}
],
"consumption": [
{
"discount": 0,
"total": 0,
"userId": "userId",
"value": 0
}
],
"entities": {
"assets": [
{
"id": "id",
"kind": "3d",
"metadata": {
"type": "3d-texture"
},
"properties": {
"size": 0,
"animationFrameCount": 0,
"bitrate": 0,
"boneCount": 0,
"channels": 0,
"classification": "effect",
"codecName": "codecName",
"description": "description",
"dimensions": [
0,
0,
0
],
"duration": 0,
"faceCount": 0,
"format": "format",
"frameRate": 0,
"hasAnimations": true,
"hasNormals": true,
"hasSkeleton": true,
"hasUVs": true,
"height": 0,
"nbFrames": 0,
"sampleRate": 0,
"transcription": {
"text": "text"
},
"vertexCount": 0,
"width": 0
},
"source": "3d23d"
}
],
"collections": [
{
"id": "id",
"name": "name"
}
],
"jobs": [
{
"id": "id",
"jobType": "assets-download",
"metadata": {
"assetIds": [
"string"
],
"error": "error",
"flow": [
{
"id": "id",
"status": "failure",
"type": "custom-model",
"assets": [
{
"assetId": "assetId",
"url": "url"
}
],
"count": 0,
"dependsOn": [
"string"
],
"includeOutputsInWorkflowJob": true,
"inputs": [
{
"name": "name",
"type": "boolean",
"allowedValues": [
{}
],
"backgroundBehavior": "opaque",
"color": true,
"costImpact": true,
"default": {},
"description": "description",
"group": "group",
"hint": "hint",
"inputs": [
{
"foo": "bar"
}
],
"items": [
[
{
"name": "name",
"type": "boolean",
"allowedValues": [
{}
],
"backgroundBehavior": "opaque",
"color": true,
"costImpact": true,
"default": {},
"description": "description",
"group": "group",
"hint": "hint",
"inputs": [
{
"foo": "bar"
}
],
"kind": "3d",
"label": "label",
"maskFrom": "maskFrom",
"max": 0,
"maxDuration": 0,
"maxLength": 0,
"maxSize": 0,
"min": 0,
"minLength": 0,
"modelTypes": [
"custom"
],
"parent": true,
"placeholder": "placeholder",
"prompt": true,
"promptSpark": true,
"ref": {
"conditional": [
"string"
],
"equal": "equal",
"name": "name",
"node": "node"
},
"required": {
"always": true,
"conditionalValues": {},
"ifDefined": {},
"ifNotDefined": {}
},
"step": 1,
"value": {}
}
]
],
"kind": "3d",
"label": "label",
"maskFrom": "maskFrom",
"max": 0,
"maxDuration": 0,
"maxLength": 0,
"maxSize": 0,
"min": 0,
"minLength": 0,
"modelTypes": [
"custom"
],
"parent": true,
"placeholder": "placeholder",
"prompt": true,
"promptSpark": true,
"ref": {
"conditional": [
"string"
],
"equal": "equal",
"name": "name",
"node": "node"
},
"required": {
"always": true,
"conditionalValues": {},
"ifDefined": {},
"ifNotDefined": {}
},
"step": 1,
"value": {}
}
],
"items": [
"string"
],
"iterationIndex": 0,
"jobId": "jobId",
"logic": {
"cases": [
{
"condition": "condition",
"value": "value"
}
],
"default": "default",
"transform": "transform"
},
"logicType": "if-else",
"loopBodyNodeIds": [
"string"
],
"loopNodeId": "loopNodeId",
"modelId": "modelId",
"output": {},
"workflowId": "workflowId"
}
],
"hint": "hint",
"input": {
"foo": "bar"
},
"output": {
"foo": "bar"
},
"outputModelId": "outputModelId",
"workflowId": "workflowId",
"workflowJobId": "workflowJobId"
},
"status": "canceled"
}
],
"models": [
{
"id": "id",
"name": "name",
"shortDescription": "shortDescription"
}
],
"users": [
{
"id": "id",
"isApiKey": true,
"apiKeyId": "apiKeyId",
"apiKeyStatus": "active",
"avatar": {
"assetId": "assetId",
"url": "url"
},
"email": "email",
"fullName": "fullName"
}
]
},
"modelUsages": [
{
"modelId": "modelId",
"points": [
{
"apiKeyCost": 0,
"apiKeyDiscount": 0,
"cost": 0,
"discount": 0,
"jobs": 0,
"time": "time"
}
]
}
],
"nsfwUsages": [
{
"label": "label",
"points": [
{
"count": 0,
"countApiKey": 0,
"time": "time"
}
]
}
],
"usages": [
{
"granularity": "15m",
"points": [
{
"apiKey": "apiKey",
"time": "time",
"value": "value"
}
],
"usageName": "background-removal"
}
]
}