Skip to main content
{
  "agent_identifier": "my-agent-id",
  "task": {
    "type": "web",
    "start_url": "https://www.google.com",
    "objective": "Find the latest news about H Company",
    "viewport_width": 1096,
    "viewport_height": 1096,
    "extra_kwargs": {}
  },
  "is_public": false,
  "timeout": 60,
  "agent_run_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

{
  "id": "b8e3a1de-cf2e-4c5d-b6c1-f9c4f514c0b1",
  "start_url": "https://www.google.com",
  "status": "pending",
  "objective": "Find the latest news about H Company",
  "created_at": "2025-07-30T12:10:01.756Z",
  "started_at": "2025-07-30T12:10:01.756Z",
  "finished_at": "2025-07-30T12:10:01.756Z",
  "viewport_width": 1096,
  "viewport_height": 1096,
  "error": "",
  "live_view_url": "https://agent-platform.hcompany.com/live-view/b8e3a1de-cf2e-4c5d-b6c1-f9c4f514c0b1",
  "is_public": false,
  "events": []
}
The Agent Platform SDK is the easiest and quickest way to build, run, and manage an AI-powered agent using H’s advanced computing technology. However, our Agent Platform API also includes a series of endpoints, including trajectory endpoints, that provide granular and precise ways of working with and managing your agents. In the Agent Platform, a trajectory represents a single execution of an agent — including its configuration, objective, execution state, and event log. This guide explains how to create, manage, and view trajectories using the Agent Platform APIs.

​
What is a trajectory?

A trajectory on the Agent Platform is designed to capture and execute the full lifecycle of a run — including the agent’s starting configuration, its objective, execution status, and a detailed timeline of events such as actions, thoughts, and messages. Trajectories are key to helping you understand agent behavior. They allow you to monitor agent performance, see what the agent is doing post-run, and retrieve essential insight for analysis and debugging.

​
What you can do with trajectories

You can use the Trajectory API to:
CapabilityDescription
Create a trajectoryStart a new agent run with a specific task or objective.
List trajectoriesRetrieve recent or historical agent runs.
Get trajectoryFetch detailed information about a specific run, including its event log.
Get objectivesReturns the list of uniques objectives the user provided in previous runs.
Update a trajectoryModify metadata or configuration for a trajectory post-creation.

​
Example

You can use thePOST /api/v1/trajectories/ endpoint to start a new agent run on the Agent Platform. This sets up the configuration for the task the agent should perform — including objective, start URL, and viewport settings. 
{
  "agent_identifier": "my-agent-id",
  "task": {
    "type": "web",
    "start_url": "https://www.google.com",
    "objective": "Find the latest news about H Company",
    "viewport_width": 1096,
    "viewport_height": 1096,
    "extra_kwargs": {}
  },
  "is_public": false,
  "timeout": 60,
  "agent_run_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

{
  "id": "b8e3a1de-cf2e-4c5d-b6c1-f9c4f514c0b1",
  "start_url": "https://www.google.com",
  "status": "pending",
  "objective": "Find the latest news about H Company",
  "created_at": "2025-07-30T12:10:01.756Z",
  "started_at": "2025-07-30T12:10:01.756Z",
  "finished_at": "2025-07-30T12:10:01.756Z",
  "viewport_width": 1096,
  "viewport_height": 1096,
  "error": "",
  "live_view_url": "https://agent-platform.hcompany.com/live-view/b8e3a1de-cf2e-4c5d-b6c1-f9c4f514c0b1",
  "is_public": false,
  "events": []
}
Some of the key properties above and defined as follows:
FieldDescription
agent_identifierThe unique ID or slug of the agent you want to run. The agent must be defined beforehand. Please use the GET /api/v1/agents/ endpoint to list available agents.
taskDescribes what the agent should do. The type must be "web" for browser-based tasks.
is_publicIf true, others can retrieve the trajectory data.
timeout(Optional) Max execution time in seconds for the agent run.
agent_run_id(Optional) Provide a self-defined identifier for the trajectory. Must be a UUID.