Get Tool Summary

Used to retrieve filtered summary data for a tool including total calls, success rate, and execution logs. This endpoint supports optional filters for date range, specific agents, and actions.

API Endpoint

Property	Value
Request Method	GET
Request URL	https://api.seliseblocks.com/tools/{tool_id}/summary

Request

Request Example

# Get summary for all time
curl -X GET 'https://api.seliseblocks.com/tools/{tool_id}/summary?project_key=YOUR_PROJECT_KEY' \
  -H 'accept: application/json'

# Get summary for specific date range
curl -X GET 'https://api.seliseblocks.com/tools/{tool_id}/summary?start_date=2026-01-01&end_date=2026-01-12&project_key=YOUR_PROJECT_KEY' \
  -H 'accept: application/json'

# Get summary for specific agent and action
curl -X GET 'https://api.seliseblocks.com/tools/{tool_id}/summary?agent_id=agent_123&action_id=get_customer&project_key=YOUR_PROJECT_KEY' \
  -H 'accept: application/json'

# Get summary with all filters
curl -X GET 'https://api.seliseblocks.com/tools/{tool_id}/summary?start_date=2026-01-01&end_date=2026-01-12&agent_id=agent_123&action_id=get_customer&project_key=YOUR_PROJECT_KEY' \
  -H 'accept: application/json'

Path Parameters

Field	Type	Required	Description
tool_id	string	Yes	The unique identifier of the tool.

Query Parameters

Field	Type	Required	Description
start_date	string	No	Start date for filtering (ISO 8601 format, e.g., "2026-01-01").
end_date	string	No	End date for filtering (ISO 8601 format, e.g., "2026-01-12").
project_key	string	No	The project key for your project.
agent_id	string	No	Filter by specific AI agent ID.
action_id	string	No	Filter by specific action ID.

Request Headers

Field	Type	Required	Description
accept	string	Yes	Accepted response format. Use application/json

note

Summary Data Filters

• All filters are optional and can be combined
• Date filters use ISO 8601 format (YYYY-MM-DD)
• If no date range is specified, returns all-time data
• Filtering by agent_id shows usage only for that specific agent
• Filtering by action_id shows data only for that specific action
• Logs are ordered by most recent first

tip

Common use cases for filtered summaries:

• Analyzing tool performance during specific time periods
• Tracking usage by individual AI agents
• Monitoring specific action performance
• Identifying trends in success rates over time
• Debugging issues during specific time windows
• Generating usage reports for billing or analytics
• Comparing performance across different agents

The summary data helps you:

• Calculate success rates and reliability metrics
• Identify performance degradation over time
• Monitor execution times and detect slowdowns
• Understand which agents use the tool most
• Track which actions are most frequently called
• Generate time-series data for visualization
• Audit tool usage for compliance

Response

Success Response (200 OK)

Returns filtered summary data for the tool.

{
  "success": true,
  "message": "Tool summary retrieved successfully",
  "data": {
    "tool_id": "tool_123",
    "agent_id": "agent_456",
    "action_id": "get_customer",
    "total_calls": 1547,
    "successful_calls": 1483,
    "failed_calls": 64,
    "success_rate": 95.86,
    "average_execution_time": 342,
    "logs": [
      {
        "created_at": "2026-01-12T07:30:15Z",
        "success": true,
        "execution_time": 287,
        "status_code": 200,
        "error_message": null
      },
      {
        "created_at": "2026-01-12T07:28:43Z",
        "success": true,
        "execution_time": 312,
        "status_code": 200,
        "error_message": null
      },
      {
        "created_at": "2026-01-12T07:25:21Z",
        "success": false,
        "execution_time": 30000,
        "status_code": 504,
        "error_message": "Gateway timeout"
      }
    ]
  },
  "status_code": 200
}

Response Fields

Field	Type	Description
success	boolean	Indicates whether the request was successful.
message	string	Human-readable status message.
data	object	Summary data object containing metrics and logs.
status_code	integer	HTTP status code (200 for success).

Data Object Fields

Field	Type	Description
tool_id	string	Unique identifier of the tool.
agent_id	string	Agent ID if filtered by agent (null otherwise).
action_id	string	Action ID if filtered by action (null otherwise).
total_calls	integer	Total number of tool executions in the filtered range.
successful_calls	integer	Number of successful executions.
failed_calls	integer	Number of failed executions.
success_rate	number	Success rate as a percentage (calculated field).
average_execution_time	integer	Average execution time in milliseconds.
logs	array	Array of recent execution log entries.

Log Entry Fields

Field	Type	Description
created_at	string	ISO 8601 timestamp when the execution occurred.
success	boolean	Whether the execution was successful.
execution_time	integer	Execution duration in milliseconds.
status_code	integer	HTTP status code returned (if applicable).
error_message	string	Error message if execution failed (null if successful).

No Data Response

Returns when no executions match the filter criteria.

{
  "success": true,
  "message": "No data found for the specified filters",
  "data": {
    "tool_id": "tool_123",
    "agent_id": "agent_456",
    "action_id": null,
    "total_calls": 0,
    "successful_calls": 0,
    "failed_calls": 0,
    "success_rate": 0,
    "average_execution_time": 0,
    "logs": []
  },
  "status_code": 200
}

Error Response (422 Unprocessable Entity)

Returns validation error details when the request parameters are invalid.

{
  "detail": [
    {
      "loc": [
        "query",
        "start_date"
      ],
      "msg": "invalid date format, use ISO 8601 (YYYY-MM-DD)",
      "type": "value_error.date"
    }
  ]
}

Error Response Fields

Field	Type	Description
detail	array	Array of validation error objects.
loc	array	Location of the error in the request (e.g., query parameter).
msg	string	Human-readable error message.
type	string	Error type identifier.

Performance Interpretation

Success Rate	Status	Recommended Action
95-100%	Excellent	Monitor for consistency
90-94%	Good	Investigate occasional failures
80-89%	Fair	Review error patterns and optimize
70-79%	Poor	Immediate attention required
Below 70%	Critical	Major issues need resolution

Error Codes

Status Code	Description	Response Type
200	Successful Response	Success
400	Bad Request - Invalid filter parameters	Bad Request
404	Not Found - Tool does not exist	Not Found
422	Validation Error - Invalid request parameters	Unprocessable Entity