Trajectories API - Eliza

Trajectories are structured records of the agent's autonomous activity: each trajectory captures LLM calls, provider accesses, token usage, and timing for one agent reasoning session. They form the raw data for fine-tuning and performance analysis.

Trajectory data is provided by the native trajectories service. The agent must be running with trajectories enabled for these endpoints to function.

Endpoints

GET /api/trajectories

List and search trajectories with filters and pagination.

Query Parameters

Parameter	Type	Required	Description
`limit`	integer	No	Results per page (min: 1, max: 500, default: 50)
`offset`	integer	No	Results to skip (default: 0)
`source`	string	No	Filter by source (e.g., `"chat"`, `"autonomy"`)
`status`	string	No	Filter by status: `"active"`, `"completed"`, `"error"`, or `"timeout"`
`startDate`	string	No	ISO 8601 start date filter
`endDate`	string	No	ISO 8601 end date filter
`search`	string	No	Text search across trajectory data
`scenarioId`	string	No	Filter by scenario ID
`batchId`	string	No	Filter by batch ID
`isTrainingData`	boolean	No	Filter to training-flagged trajectories only

Response

json

{
  "trajectories": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "agentId": "agent-uuid",
      "roomId": null,
      "entityId": null,
      "conversationId": null,
      "source": "autonomy",
      "status": "completed",
      "startTime": 1718000000000,
      "endTime": 1718000010000,
      "durationMs": 10000,
      "llmCallCount": 3,
      "providerAccessCount": 2,
      "totalPromptTokens": 1200,
      "totalCompletionTokens": 340,
      "metadata": {},
      "createdAt": "2024-06-10T12:00:00.000Z",
      "updatedAt": "2024-06-10T12:00:10.000Z"
    }
  ],
  "total": 142,
  "offset": 0,
  "limit": 50
}

GET /api/trajectories/stats

Get aggregate trajectory statistics.

Response

json

{
  "totalTrajectories": 142,
  "totalLlmCalls": 891,
  "totalProviderAccesses": 320,
  "totalPromptTokens": 450000,
  "totalCompletionTokens": 128000,
  "averageDurationMs": 8500,
  "bySource": {
    "chat": 98,
    "autonomy": 44
  },
  "byModel": {
    "claude-opus-4-7": 500,
    "claude-sonnet-4-5": 391
  }
}

GET /api/trajectories/:id

Get full trajectory details including all LLM calls and provider accesses.

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Trajectory ID

Response

json

{
  "trajectory": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "agentId": "agent-uuid",
    "source": "autonomy",
    "status": "completed",
    "startTime": 1718000000000,
    "endTime": 1718000010000,
    "durationMs": 10000,
    "llmCallCount": 3,
    "providerAccessCount": 2,
    "totalPromptTokens": 1200,
    "totalCompletionTokens": 340,
    "metadata": {}
  },
  "llmCalls": [
    {
      "id": "call-001",
      "trajectoryId": "550e8400-e29b-41d4-a716-446655440000",
      "stepId": "step-0",
      "model": "claude-opus-4-7",
      "systemPrompt": "You are Eliza...",
      "userPrompt": "What should I post today?",
      "response": "Here are some ideas...",
      "temperature": 0.7,
      "maxTokens": 1024,
      "purpose": "action_selection",
      "actionType": "autonomy",
      "latencyMs": 1200,
      "promptTokens": 800,
      "completionTokens": 340,
      "timestamp": 1718000001000,
      "createdAt": "2024-06-10T12:00:01.000Z"
    }
  ],
  "providerAccesses": [
    {
      "id": "access-001",
      "trajectoryId": "550e8400-e29b-41d4-a716-446655440000",
      "stepId": "step-0",
      "providerName": "twitter",
      "purpose": "context_retrieval",
      "data": {},
      "timestamp": 1718000000500,
      "createdAt": "2024-06-10T12:00:00.500Z"
    }
  ]
}

GET /api/trajectories/config

Get trajectory logging configuration.

Response

json

{
  "enabled": true
}

PUT /api/trajectories/config

Enable or disable trajectory logging.

Request

json

{
  "enabled": false
}

Parameter	Type	Required	Description
`enabled`	boolean	Yes	`true` to enable trajectory logging, `false` to disable

Response

json

{
  "enabled": false
}

POST /api/trajectories/export

Export trajectories in various formats. Returns a file download.

Request

json

{
  "format": "json",
  "includePrompts": true,
  "trajectoryIds": ["550e8400-e29b-41d4-a716-446655440000"],
  "startDate": "2024-06-01",
  "endDate": "2024-06-30"
}

Parameter	Type	Required	Description
`format`	string	Yes	Export format: `"json"`, `"csv"`, `"art"`, or `"zip"`
`includePrompts`	boolean	No	Whether to include full prompt/response text (default: `false`)
`trajectoryIds`	string[]	No	Specific trajectory IDs to export. Exports all if omitted
`startDate`	string	No	ISO 8601 start date filter
`endDate`	string	No	ISO 8601 end date filter
`scenarioId`	string	No	Filter by scenario ID
`batchId`	string	No	Filter by batch ID

Response

File download with appropriate Content-Type and Content-Disposition headers:

Format	Content-Type
`json`	`application/json`
`csv`	`text/csv`
`art`	`application/octet-stream`
`zip`	`application/zip`

DELETE /api/trajectories

Delete trajectories by ID or delete all trajectories.

Request (delete specific)

json

{
  "trajectoryIds": ["550e8400-e29b-41d4-a716-446655440000"]
}

Request (delete all)

json

{
  "all": true
}

Parameter	Type	Required	Description
`trajectoryIds`	string[]	No	List of trajectory IDs to delete
`all`	boolean	No	Set to `true` to delete all trajectories

Response

json

{
  "deleted": 5
}