New VDF AI Enterprise is now available on AWS Marketplace
API Reference

Executions

An execution records one agent run: the prompt, the final output, token usage, the status and when it started and finished. Runs that belong to the same conversation share a session_id; see Sessions for the conversations and their messages.

These endpoints only ever return your own executions.

Endpoints 2

Paths are relative to /agent-hub-api

The execution object

One agent run.

Attributes

  • id string

    Unique identifier for the execution (a UUID).

  • session_id nullable string

    Id of the session the run belongs to.

  • user_id nullable integer

    Id of the user the run was made for.

  • client_id string

    Identifier of the client application that started the run, for example web, or unknown when none was given.

  • app_id nullable string

    Identifier of the external application that started the run, or null.

  • agent_id nullable string

    Id of the agent that ran, when known.

  • agent_name nullable string

    Name of the agent that ran, kept even if the agent is later renamed or deleted.

  • prompt string

    The prompt the agent was given.

  • context object

    The run context the agent received, including values the deployment adds, such as user_id, session_id and workspace details. Empty when your administrator has turned off context logging.

  • output nullable string

    The agent's final answer. null while the run is pending.

  • usage_stats object

    Token usage for the whole run.

    Show child attributes Hide child attributes
    • input integer

      Input tokens.

    • output integer

      Output tokens.

    • total integer

      Input and output tokens together.

  • status string

    PENDING while the run is in progress, then SUCCESS or FAILURE.

    Possible values
    • PENDING
    • SUCCESS
    • FAILURE
  • error_message nullable string

    Why the run failed, for FAILURE runs.

  • created_at string

    When the run started (UTC, ISO 8601).

  • completed_at nullable string

    When the run finished (UTC, ISO 8601), or null while it is pending.

The execution object 
{
  "id": "e4a7c2d9-1b3f-4c8e-9a5d-6f2b8e1c3a70",
  "session_id": "5b8e1f3a-2c9d-4a67-b1e4-7f0c3d9a2e58",
  "user_id": 42,
  "client_id": "web",
  "app_id": null,
  "agent_id": "9d2f4b61-3a7c-4e15-8b0d-2c6e9f1a7b34",
  "agent_name": "Release Manager",
  "prompt": "Draft the release notes for version 4.2 from this week's merged changes.",
  "context": {
    "client_id": "web",
    "user_id": 42,
    "agent_id": "9d2f4b61-3a7c-4e15-8b0d-2c6e9f1a7b34",
    "session_id": "5b8e1f3a-2c9d-4a67-b1e4-7f0c3d9a2e58"
  },
  "output": "## Release 4.2\n\n### Features\n- Added bulk export for invoices.\n\n### Fixes\n- Fixed rounding in quarterly totals.",
  "usage_stats": {
    "input": 1840,
    "output": 412,
    "total": 2252
  },
  "status": "SUCCESS",
  "error_message": null,
  "created_at": "2026-09-01T09:29:48.301127",
  "completed_at": "2026-09-01T09:30:03.884590"
}

List executions

GET /agent-hub-api/api/monitoring/executions

Returns the caller's executions, newest first, with per-status totals.

Filters combine. status_counts counts every execution that matches all the other filters regardless of status, so you can show totals per status while listing only one of them.

Authentication
Bearer token How it works

Query parameters

  • limit integer

    Maximum number of executions to return.

    Defaults to 20.

  • offset integer

    Number of executions to skip.

    Defaults to 0.

  • agent_name string

    Only executions of the agent with exactly this name.

  • status string

    Only executions with this status: PENDING, SUCCESS or FAILURE.

  • client_id string

    Only executions started by this client application.

  • session_id string

    Only executions in this session. A value that is not a UUID returns an empty list.

  • date_from string

    Only executions started at or after this time: an ISO 8601 date-time such as 2026-09-01T00:00:00Z, or a date such as 2026-09-01. A value that cannot be parsed is ignored.

  • date_to string

    Only executions started at or before this time, in the same formats as date_from.

Returns

Returns data, a page of execution objects; status_counts, the number of matching executions per status; and pagination with total, limit, offset and has_more.

Request 
curl "$VDF_BASE_URL/agent-hub-api/api/monitoring/executions?agent_name=Release%20Manager&limit=20" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"
Response 200 
{
  "success": true,
  "data": [
    {
      "id": "e4a7c2d9-1b3f-4c8e-9a5d-6f2b8e1c3a70",
      "session_id": "5b8e1f3a-2c9d-4a67-b1e4-7f0c3d9a2e58",
      "user_id": 42,
      "client_id": "web",
      "app_id": null,
      "agent_id": "9d2f4b61-3a7c-4e15-8b0d-2c6e9f1a7b34",
      "agent_name": "Release Manager",
      "prompt": "Draft the release notes for version 4.2 from this week's merged changes.",
      "context": {
        "client_id": "web",
        "user_id": 42,
        "agent_id": "9d2f4b61-3a7c-4e15-8b0d-2c6e9f1a7b34",
        "session_id": "5b8e1f3a-2c9d-4a67-b1e4-7f0c3d9a2e58"
      },
      "output": "## Release 4.2\n\n### Features\n- Added bulk export for invoices.\n\n### Fixes\n- Fixed rounding in quarterly totals.",
      "usage_stats": {
        "input": 1840,
        "output": 412,
        "total": 2252
      },
      "status": "SUCCESS",
      "error_message": null,
      "created_at": "2026-09-01T09:29:48.301127",
      "completed_at": "2026-09-01T09:30:03.884590"
    }
  ],
  "status_counts": {
    "SUCCESS": 18,
    "FAILURE": 2
  },
  "pagination": {
    "total": 20,
    "limit": 20,
    "offset": 0,
    "has_more": false
  }
}

List risk classifications

GET /agent-hub-api/api/monitoring/executions/classifications

Returns the latest successful EU AI Act risk classification for each AI system the caller has classified.

A risk classification is a successful run of the risk classification agent whose run context carries the system_id of an AI system in your compliance register. This endpoint looks at your 500 most recent successful runs of that agent and returns the newest one for each system_id, with the agent's answer parsed into a risk tier. The agent name matches in its common spellings, for example risk_classifier, RiskClassifier and Risk Classifier.

Authentication
Bearer token How it works

Query parameters

  • agent_name string

    Name of the agent whose runs count as classifications.

    Defaults to risk_classifier.

Returns

Returns data, an object keyed by AI system id. Each value has execution_id, classified_at, risk_tier (unacceptable, high, limited, minimal or unclassified), annex_iii_category, rationale and the agent's raw output.

Request 
curl "$VDF_BASE_URL/agent-hub-api/api/monitoring/executions/classifications" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"
Response 200 
{
  "success": true,
  "data": {
    "a8c4e1f7-2b9d-4c63-9e05-7d1f3b8a2c64": {
      "execution_id": "f1b8d3a6-4e2c-4a97-b5d0-8c3e1f6a9b27",
      "classified_at": "2026-09-02T14:05:11.208334",
      "risk_tier": "high",
      "annex_iii_category": "4(a)",
      "rationale": "The system ranks job applicants for shortlisting, a use listed in Annex III point 4(a), so it is high-risk under Article 6(2).",
      "output": "{\"risk_tier\": \"high\", \"annex_iii_category\": \"4(a)\", \"rationale\": \"The system ranks job applicants for shortlisting, a use listed in Annex III point 4(a), so it is high-risk under Article 6(2).\"}"
    }
  }
}