POST /mltk/run_history

Description. Paginate agent run history. Creates a synchronous Splunk search job (POST /search/jobs), polls it (isDone/isFailed/isFinalized, up to 120 × 1s), retrieves results (/results), and optionally deletes a prior job to free resources. The SPL query is built dynamically against the configured run-history index and sourcetype="ai_agent:response".

Authorization. If agent_name is supplied, each name is validated against the user's ACL via AgentManager.get_agent() (403 on the first denial). Without agent_name, AgentManager.list_agents() filters to the user's readable set.

Body (JSON).

Field	Type	Default	Notes
offset	int	0	Page start, ≥ 0
count	int	100	Page size, 1–50000
agent_name	string or string[]	—	Filter; ACL-checked
session_id	string	—
request_id	string	—
earliest	string	-24h	Splunk time spec
latest	string	now	Splunk time spec
sid	string	—	Reuse an existing search job for pagination
previous_sid	string	—	If set, the previous job is deleted
total_results	int	—	Skips count-fetch when paging with sid

Response (200).

{
  "history": [
    {
      "_time":           "1704067200",
      "request_id":      "req-123",
      "session_id":      "sess-456",
      "agent_name":      "my_agent",
      "prompt":          "What is the weather?",
      "response":        "The weather is sunny.",
      "type":            "run_finished",
      "processing_time": "2.5",
      "row_index":       "0",
      "search_id":       "search-789"
    }
  ],
  "pagination": {
    "offset":      0,
    "count":       50,
    "total":       500,
    "returned":    50,
    "has_more":    true,
    "next_offset": 50
  },
  "sid": "1715425200.999"
}

Error responses.

Status	Body	Cause
400	{"error":"offset must be non-negative"} / "count must be between 1 and 50000"	Validation
400	{"message":"No Authorized Agents available with these filters", "history":[]}	No agents pass ACL
403	{"error":"User is not authorized to access the following agent(s): ..."}	ACL denial
500	{"error":"Search with particular SID not found."}	sid no longer exists
500	{"error":"Failed to retrieve run history: ..."}	Unexpected error

Examples.

# First page filtered by agent
curl -sk -u "$SPLUNK_USER:$SPLUNK_PASSWORD" -X POST 
  -H "Content-Type: application/json" 
  --data '{"agent_name":"my_agent","offset":0,"count":50,"earliest":"-7d"}' 
  "$SPLUNK_HOST/servicesNS/nobody/Splunk_ML_Toolkit/mltk/run_history?output_mode=json"

# Subsequent page reusing the sid
curl -sk -u "$SPLUNK_USER:$SPLUNK_PASSWORD" -X POST 
  -H "Content-Type: application/json" 
  --data '{"sid":"1715425200.999","offset":50,"count":50,"total_results":500}' 
  "$SPLUNK_HOST/servicesNS/nobody/Splunk_ML_Toolkit/mltk/run_history?output_mode=json"

Source. bin/rest_handlers/hec_operations.py, bin/rest_handlers/run_history.py, bin/run_history/search_utils.py, bin/hec/*.