List AI Tool Usages (v1)

Method & Path

GET /api/v1/workspace/:workspaceId/ai/usages

Description

Get a paginated list of AI tool usages with optional filtering.

Authentication

Required: Workspace authentication. User must be authenticated as Workspace Owner or Staff with workspace permissions.

Headers

Authorization: Bearer <workspace_token>
Content-Type: application/json

Path Parameters

Parameter	Type	Required	Description
workspaceId	string	Yes	Workspace identifier

Query Parameters

Parameter	Type	Required	Description
limit	number	No	Number of results per page (default: 50)
offset	number	No	Number of results to skip (default: 0)
toolType	string	No	Filter by tool type (product-marketing-post, image-generation, session-summary, other)
status	string	No	Filter by status (pending, completed, failed)

Response 200 OK

{
  "usages": [
    {
      "id": "507f1f77bcf86cd799439011",
      "workspaceId": "507f1f77bcf86cd799439012",
      "toolType": "product-marketing-post",
      "status": "completed",
      "cost": 0.10,
      "inputData": {},
      "responseData": {
        "postText": "Check out our new product!",
        "overlaysSaved": []
      },
      "createdAt": "2025-01-15T10:30:00.000Z",
      "completedAt": "2025-01-15T10:30:05.000Z"
    }
  ],
  "pagination": {
    "total": 250,
    "limit": 50,
    "offset": 0,
    "hasMore": true
  }
}

Response Fields

usages

Array of AI tool usage objects:

• id (string): Usage identifier
• workspaceId (string): Workspace identifier
• toolType (string): Tool type (product-marketing-post, image-generation, session-summary, other)
• status (string): Status (pending, completed, failed)
• cost (number): Cost of this usage
• inputData (object): Input data for the AI tool
• responseData (object): Response data from the AI tool
• createdAt (string): Creation timestamp (ISO 8601 format)
• completedAt (string | null): Completion timestamp (ISO 8601 format)

pagination

See List SMS Messages for pagination fields.

Common Errors

400 Bad Request: Invalid query parameters

401 Unauthorized: Missing or invalid authentication token

404 Not Found: Workspace not found

500 Internal Server Error: Server error occurred while processing the request