Codegen - The SWE that Never Sleeps

The Agent Run Logs API allows you to retrieve detailed execution logs for agent runs, providing insights into the agent’s thought process, tool usage, and execution flow.

Endpoint

GET /v1/organizations/{org_id}/agent/run/{agent_run_id}/logs

Authentication

This endpoint requires API token authentication. Include your token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Parameters

Parameter	Type	Required	Description
`org_id`	integer	Yes	Your organization ID
`agent_run_id`	integer	Yes	The ID of the agent run to retrieve logs for
`skip`	integer	No	Number of logs to skip for pagination (default: 0)
`limit`	integer	No	Maximum number of logs to return (default: 100, max: 100)

Response Structure

The endpoint returns an AgentRunWithLogsResponse object containing the agent run details and paginated logs:

{
  "id": 12345,
  "organization_id": 67890,
  "status": "completed",
  "created_at": "2024-01-15T10:30:00Z",
  "web_url": "https://app.codegen.com/agent/trace/12345",
  "result": "Task completed successfully",
  "logs": [
    {
      "agent_run_id": 12345,
      "created_at": "2024-01-15T10:30:15Z",
      "tool_name": "ripgrep_search",
      "message_type": "ACTION",
      "thought": "I need to search for the user's function in the codebase",
      "observation": {
        "status": "success",
        "results": ["Found 3 matches..."]
      },
      "tool_input": {
        "query": "function getUserData",
        "file_extensions": [".js", ".ts"]
      },
      "tool_output": {
        "matches": 3,
        "files": ["src/user.js", "src/api.ts"]
      }
    }
  ],
  "total_logs": 25,
  "page": 1,
  "size": 100,
  "pages": 1
}

Agent Run Log Fields

Each log entry in the logs array contains the following fields:

Core Fields

Field	Type	Description
`agent_run_id`	integer	The ID of the agent run this log belongs to
`created_at`	string	ISO 8601 timestamp when the log entry was created
`message_type`	string	The type of log entry (see Log Types below)

Agent Reasoning Fields

Field	Type	Description
`thought`	string \| null	The agent’s internal reasoning or thought process for this step

Tool Execution Fields

Field	Type	Description
`tool_name`	string \| null	Name of the tool being executed (e.g., “ripgrep_search”, “file_write”)
`tool_input`	object \| null	JSON object containing the parameters passed to the tool
`tool_output`	object \| null	JSON object containing the tool’s execution results
`observation`	object \| string \| null	The agent’s observation of the tool execution results or other contextual data

Log Types

The message_type field indicates the type of log entry. Here are the possible values:

Plan Agent Types

Type	Description
`ACTION`	The agent is executing a tool or taking an action
`PLAN_EVALUATION`	The agent is evaluating or updating its plan
`FINAL_ANSWER`	The agent is providing its final response or conclusion
`ERROR`	An error occurred during execution
`USER_MESSAGE`	A message from the user (e.g., interruptions or additional context)
`USER_GITHUB_ISSUE_COMMENT`	A comment from a GitHub issue that the agent is processing

PR Agent Types

Type	Description
`INITIAL_PR_GENERATION`	The agent is generating the initial pull request
`DETECT_PR_ERRORS`	The agent is detecting errors in a pull request
`FIX_PR_ERRORS`	The agent is fixing errors found in a pull request
`PR_CREATION_FAILED`	Pull request creation failed
`PR_EVALUATION`	The agent is evaluating a pull request

Commit Agent Types

Type	Description
`COMMIT_EVALUATION`	The agent is evaluating commits

Link Types

Type	Description
`AGENT_RUN_LINK`	A link to another related agent run

Field Population Patterns

Different log types populate different fields:

ACTION Logs

Always have: tool_name, tool_input, tool_output
Often have: thought, observation
Example: Tool executions like searching code, editing files, creating PRs

PLAN_EVALUATION Logs

Always have: thought
May have: observation
Rarely have: Tool-related fields
Example: Agent reasoning about next steps

ERROR Logs

Always have: observation (containing error details)
May have: tool_name (if error occurred during tool execution)
Example: Failed tool executions or system errors

FINAL_ANSWER Logs

Always have: observation (containing the final response)
May have: thought
Example: Agent’s final response to the user

Usage Examples

Basic Log Retrieval

import requests

url = "https://api.codegen.com/v1/organizations/67890/agent/run/12345/logs"
headers = {"Authorization": "Bearer YOUR_API_TOKEN"}

response = requests.get(url, headers=headers)
data = response.json()

print(f"Agent run status: {data['status']}")
print(f"Total logs: {data['total_logs']}")

for log in data['logs']:
    print(f"[{log['created_at']}] {log['message_type']}: {log['thought']}")

Filtering by Log Type

# Get only ACTION logs to see tool executions
action_logs = [log for log in data['logs'] if log['message_type'] == 'ACTION']

for log in action_logs:
    print(f"Tool: {log['tool_name']}")
    print(f"Input: {log['tool_input']}")
    print(f"Output: {log['tool_output']}")
    print("---")

Pagination Example

# Get logs in batches of 50
skip = 0
limit = 50
all_logs = []

while True:
    url = f"https://api.codegen.com/v1/organizations/67890/agent/run/12345/logs?skip={skip}&limit={limit}"
    response = requests.get(url, headers=headers)
    data = response.json()

    all_logs.extend(data['logs'])

    if len(data['logs']) < limit:
        break  # No more logs

    skip += limit

print(f"Retrieved {len(all_logs)} total logs")

Debugging Failed Runs

# Find error logs to debug issues
error_logs = [log for log in data['logs'] if log['message_type'] == 'ERROR']

for error_log in error_logs:
    print(f"Error at {error_log['created_at']}: {error_log['observation']}")
    if error_log['tool_name']:
        print(f"Failed tool: {error_log['tool_name']}")

Common Use Cases

1. Building Monitoring Dashboards

Use the logs to create dashboards showing:

Agent execution progress
Tool usage patterns
Error rates and types
Execution timelines

2. Debugging Agent Behavior

Analyze logs to understand:

Why an agent made certain decisions
Where errors occurred in the execution flow
What tools were used and their results

3. Audit and Compliance

Track agent actions for:

Code change auditing
Compliance reporting
Security monitoring

4. Performance Analysis

Monitor:

Tool execution times
Common failure patterns
Agent reasoning efficiency

Rate Limits

60 requests per 60 seconds per API token
Rate limits are shared across all API endpoints

Error Responses

Status Code	Description
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API token
403	Forbidden - Insufficient permissions
404	Not Found - Agent run not found
429	Too Many Requests - Rate limit exceeded

Feedback and Support

Since this endpoint is in ALPHA, we’d love your feedback! Please reach out through:

The structure and fields of this API may change as we gather feedback and improve the service. We’ll provide advance notice of any breaking changes.

Guides

Endpoints

Retrieving Traces

Endpoint

Authentication

Parameters

Response Structure

Agent Run Log Fields

Core Fields

Agent Reasoning Fields

Tool Execution Fields

Log Types

Plan Agent Types

PR Agent Types

Commit Agent Types

Link Types

Field Population Patterns

ACTION Logs

PLAN_EVALUATION Logs

ERROR Logs

FINAL_ANSWER Logs

Usage Examples

Basic Log Retrieval

Filtering by Log Type

Debugging Failed Runs

Common Use Cases

1. Building Monitoring Dashboards

2. Debugging Agent Behavior

3. Audit and Compliance

4. Performance Analysis

Rate Limits

Error Responses

Feedback and Support

Guides

Endpoints

​Endpoint

​Authentication

​Parameters

​Response Structure

​Agent Run Log Fields

​Core Fields

​Agent Reasoning Fields

​Tool Execution Fields

​Log Types

​Plan Agent Types

​PR Agent Types

​Commit Agent Types

​Link Types

​Field Population Patterns

​ACTION Logs

​PLAN_EVALUATION Logs

​ERROR Logs

​FINAL_ANSWER Logs

​Usage Examples

​Basic Log Retrieval

​Filtering by Log Type

​Pagination Example

​Debugging Failed Runs

​Common Use Cases

​1. Building Monitoring Dashboards

​2. Debugging Agent Behavior

​3. Audit and Compliance

​4. Performance Analysis

​Rate Limits

​Error Responses

​Feedback and Support

Endpoint

Authentication

Parameters

Response Structure

Agent Run Log Fields

Core Fields

Agent Reasoning Fields

Tool Execution Fields

Log Types

Plan Agent Types

PR Agent Types

Commit Agent Types

Link Types

Field Population Patterns

ACTION Logs

PLAN_EVALUATION Logs

ERROR Logs

FINAL_ANSWER Logs

Usage Examples

Basic Log Retrieval

Filtering by Log Type

Pagination Example

Debugging Failed Runs

Common Use Cases

1. Building Monitoring Dashboards

2. Debugging Agent Behavior

3. Audit and Compliance

4. Performance Analysis

Rate Limits

Error Responses

Feedback and Support