> ## Documentation Index
> Fetch the complete documentation index at: https://docs.incidentfox.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Run Agent

> Trigger an investigation via the API

## Endpoint

```
POST /api/v1/agents/run
```

Triggers an investigation using the specified agent.

## Authentication

<Note>
  Requires Team Token or Admin Token.
</Note>

## Request

### Headers

| Header          | Required | Description         |
| --------------- | -------- | ------------------- |
| `Authorization` | Yes      | `Bearer YOUR_TOKEN` |
| `Content-Type`  | Yes      | `application/json`  |

### Body Parameters

| Parameter    | Type    | Required | Description                         |
| ------------ | ------- | -------- | ----------------------------------- |
| `agent_name` | string  | Yes      | Agent to invoke                     |
| `message`    | string  | Yes      | Investigation request               |
| `context`    | object  | No       | Additional context                  |
| `async`      | boolean | No       | Return immediately (default: false) |

### Available Agents

| Agent                 | Description                      |
| --------------------- | -------------------------------- |
| `planner`             | Orchestrates full investigations |
| `investigation_agent` | Comprehensive troubleshooting    |
| `k8s_agent`           | Kubernetes-focused               |
| `aws_agent`           | AWS-focused                      |
| `coding_agent`        | Code analysis                    |

## Request Example

```bash theme={null}
curl -X POST https://api.incidentfox.ai/api/v1/agents/run \
  -H "Authorization: Bearer $TEAM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "planner",
    "message": "Investigate high latency in the payments service",
    "context": {
      "service": "payments",
      "environment": "production",
      "severity": "high"
    }
  }'
```

## Response

### Success Response (200)

```json theme={null}
{
  "investigation_id": "inv_abc123",
  "status": "completed",
  "duration_seconds": 45,
  "result": {
    "summary": "Payment service experiencing elevated latency due to database connection pool exhaustion",
    "root_cause": {
      "description": "RDS connection pool at maximum capacity (100/100 connections)",
      "confidence": 92,
      "evidence": [
        "CloudWatch RDS connections metric at 100%",
        "Application logs show 'connection timeout' errors",
        "Spike correlates with deployment at 14:32 UTC"
      ]
    },
    "timeline": [
      {
        "timestamp": "2024-01-15T14:32:00Z",
        "event": "New deployment rolled out"
      },
      {
        "timestamp": "2024-01-15T14:35:00Z",
        "event": "Connection count started increasing"
      },
      {
        "timestamp": "2024-01-15T14:42:00Z",
        "event": "Connection pool exhausted"
      }
    ],
    "affected_systems": [
      "payments-service",
      "checkout-service",
      "RDS primary"
    ],
    "recommendations": [
      {
        "priority": "high",
        "action": "Increase RDS max_connections parameter"
      },
      {
        "priority": "medium",
        "action": "Review connection pool settings in application config"
      },
      {
        "priority": "low",
        "action": "Consider connection pooler like PgBouncer"
      }
    ]
  },
  "tools_used": [
    "get_cloudwatch_logs",
    "get_cloudwatch_metrics",
    "get_pod_logs",
    "search_github_code"
  ],
  "created_at": "2024-01-15T14:45:00Z"
}
```

### Async Response (202)

When `async: true`:

```json theme={null}
{
  "investigation_id": "inv_abc123",
  "status": "running",
  "poll_url": "/api/v1/agents/status/inv_abc123",
  "created_at": "2024-01-15T14:45:00Z"
}
```

### Error Responses

**400 Bad Request**

```json theme={null}
{
  "error": {
    "code": "invalid_request",
    "message": "agent_name is required"
  }
}
```

**401 Unauthorized**

```json theme={null}
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or expired token"
  }
}
```

**429 Rate Limited**

```json theme={null}
{
  "error": {
    "code": "rate_limited",
    "message": "Too many investigation requests",
    "retry_after": 60
  }
}
```

## Async Investigations

For long-running investigations, use async mode:

```bash theme={null}
curl -X POST https://api.incidentfox.ai/api/v1/agents/run \
  -H "Authorization: Bearer $TEAM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "planner",
    "message": "Full system health check",
    "async": true
  }'
```

Then poll for results:

```bash theme={null}
curl -X GET https://api.incidentfox.ai/api/v1/agents/status/inv_abc123 \
  -H "Authorization: Bearer $TEAM_TOKEN"
```

## Context Parameters

Provide additional context to improve investigation accuracy:

```json theme={null}
{
  "context": {
    "service": "payments",
    "environment": "production",
    "namespace": "checkout",
    "severity": "high",
    "related_alert": "alert_xyz789",
    "time_window": "1h",
    "hint": "Check recent deployments"
  }
}
```

| Context Field   | Description              |
| --------------- | ------------------------ |
| `service`       | Target service name      |
| `environment`   | prod, staging, dev       |
| `namespace`     | Kubernetes namespace     |
| `severity`      | high, medium, low        |
| `related_alert` | Alert ID for context     |
| `time_window`   | Investigation time range |
| `hint`          | Additional guidance      |

## Code Examples

### Python

```python theme={null}
import requests

response = requests.post(
    "https://api.incidentfox.ai/api/v1/agents/run",
    headers={
        "Authorization": f"Bearer {TEAM_TOKEN}",
        "Content-Type": "application/json"
    },
    json={
        "agent_name": "planner",
        "message": "Investigate high latency in payments"
    }
)

result = response.json()
print(f"Root cause: {result['result']['root_cause']['description']}")
```

### JavaScript

```javascript theme={null}
const response = await fetch('https://api.incidentfox.ai/api/v1/agents/run', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${TEAM_TOKEN}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    agent_name: 'planner',
    message: 'Investigate high latency in payments'
  })
});

const result = await response.json();
console.log(`Root cause: ${result.result.root_cause.description}`);
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Check Status" icon="clock" href="/api-reference/agent/status">
    Poll investigation status
  </Card>

  <Card title="Configuration" icon="sliders" href="/api-reference/config/effective">
    Get team configuration
  </Card>
</CardGroup>