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

# Request Log Debugging

> How to use StackOne's Log endpoints to debug failed action calls

StackOne records a **request log** for every API call it handles on your behalf, covering action (RPC) runs, MCP tool calls, and the connector steps behind them. This guide shows which endpoints to call, in what order, when debugging failures.

<Info>
  This guide covers **request logs** only, the same data shown on the [Request Logs](/connect/troubleshooting) dashboard page. It does not cover platform or audit logs.

  The API follows the same drill-down hierarchy as the dashboard: **list → detail → advanced / steps / defender**.
</Info>

To build admin or customer-facing log dashboards, see [Request Log Dashboards](/features/observability/request-log-dashboards). To export logs into Grafana, Datadog, or a data warehouse, see [Observability & Log Sync](/features/observability/observability-and-log-sync).

***

## Drill-down hierarchy

Start at the list endpoint and drill down only when you need more detail, exactly as the dashboard does.

```mermaid theme={null}
flowchart TB
    List["POST /logs<br/>List request logs<br/>(filter by account, connector, time, status)"]
    Detail["GET /logs/actions/{actionRunId}<br/>Request summary"]
    Steps["GET /logs/actions/{actionRunId}/steps<br/>Execution steps"]
    Advanced["GET /logs/actions/{actionRunId}/advanced<br/>Full request/response bodies"]
    StepAdv["GET /logs/actions/{actionRunId}/steps/{stepIndex}/advanced<br/>Step request/response bodies"]
    Defender["GET /logs/actions/{actionRunId}/defender<br/>Defender scan results"]

    List -->|"action_run_id from list row"| Detail
    Detail --> Steps
    Detail --> Advanced
    Detail --> Defender
    Steps -->|"step_index from step row"| StepAdv
```

| Order | Endpoint | Returns |
| - | - | - |
| 1. List | [List Logs](/platform/api-reference/logs/list-logs) `POST /logs` | Paginated summary rows. Each row includes an `action_run_id` for drill-down. |
| 2. Detail | [Get Action Log](/platform/api-reference/logs/get-action-log) `GET /logs/actions/{actionRunId}` | Full metadata for a single request (status, duration, connector, account, action). |
| 3a. Steps | [List Action Step Logs](/platform/api-reference/logs/list-action-step-logs) `GET /logs/actions/{actionRunId}/steps` | Connector execution steps within the request. Requires `page` and `page_size` query parameters. |
| 3b. Advanced | [Get Action Advanced Log](/platform/api-reference/logs/get-action-advanced-log) `GET /logs/actions/{actionRunId}/advanced` | HTTP request and response bodies. |
| 3c. Defender | [Get Action Defender Log](/platform/api-reference/logs/get-action-defender-log) `GET /logs/actions/{actionRunId}/defender` | [Defender](/secure/defender) scan output for AI agent tool calls. |
| 4. Single step | [Get Step Log](/platform/api-reference/logs/get-step-log) / [Get Step Advanced Log](/platform/api-reference/logs/get-step-advanced-log) | Summary or full payloads for a single step. |

For dashboard KPIs without listing individual rows, use [Get Logs Stats Aggregate](/platform/api-reference/logs/get-logs-stats-aggregate) and [Get Logs Stats Dimensions](/platform/api-reference/logs/get-logs-stats-dimensions).

***

## List filters

[List Logs](/platform/api-reference/logs/list-logs) accepts a `POST` body with filters and pagination. Common filters mirror the dashboard search bar:

| Filter | Use for |
| - | - |
| `account_secure_id` | Scope to one or more linked accounts (required for customer-facing views) |
| `connector_key` / `provider` | Filter by integration (e.g. `bamboohr`, `workday`) |
| `start_time` / `end_time` | Time window |
| `success` / `status_code` | Errors only, or specific HTTP statuses |
| `action_id` | Filter by specific action |

See the [List Logs API reference](/platform/api-reference/logs/list-logs) for the full filter schema.

### Example: list recent errors for an account

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST "https://api.stackone.com/logs" \
      -H "Authorization: Basic $(printf '%s' "${STACKONE_API_KEY}:" | base64)" \
      -H "Content-Type: application/json" \
      -d '{
        "filters": {
          "start_time": "2024-01-15T00:00:00Z",
          "end_time": "2024-01-15T23:59:59Z",
          "account_secure_id": ["45355976281015164504"],
          "success": false
        },
        "page": 1,
        "page_size": 50
      }'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests
    import base64
    import os

    api_key = os.environ["STACKONE_API_KEY"]
    headers = {
        "Authorization": f"Basic {base64.b64encode(f'{api_key}:'.encode()).decode()}",
        "Content-Type": "application/json",
    }

    response = requests.post(
        "https://api.stackone.com/logs",
        headers=headers,
        json={
            "filters": {
                "start_time": "2024-01-15T00:00:00Z",
                "end_time": "2024-01-15T23:59:59Z",
                "account_secure_id": ["45355976281015164504"],
                "success": False,
            },
            "page": 1,
            "page_size": 50,
        },
    )
    logs = response.json()["data"]
    ```
  </Tab>
</Tabs>

Each list row includes an `action_run_id`. Pass that to the detail and drill-down endpoints.

***

## Debug a failed request

Trace a single failed call from the list through to the step that failed.

| Order | Endpoint | ID from previous call |
| - | - | - |
| 1. Find the log | [List Logs](/platform/api-reference/logs/list-logs) | — |
| 2. Get request summary | [Get Action Log](/platform/api-reference/logs/get-action-log) | `action_run_id` from order 1 |
| 3. List execution steps | [List Action Step Logs](/platform/api-reference/logs/list-action-step-logs) | same `action_run_id` |
| 4. Inspect a failed step | [Get Step Advanced Log](/platform/api-reference/logs/get-step-advanced-log) | `action_run_id` + `step_index` from order 3 |
| 5. (Optional) Full request payload | [Get Action Advanced Log](/platform/api-reference/logs/get-action-advanced-log) | same `action_run_id` |
| 6. (Optional) Defender scan | [Get Action Defender Log](/platform/api-reference/logs/get-action-defender-log) | same `action_run_id` |

```mermaid theme={null}
sequenceDiagram
    participant App as Your App
    participant StackOne as StackOne Logs API

    App->>StackOne: POST /logs (filter: success=false)
    StackOne-->>App: action_run_id

    App->>StackOne: GET /logs/actions/{actionRunId}
    StackOne-->>App: Request summary

    App->>StackOne: GET /logs/actions/{actionRunId}/steps
    StackOne-->>App: Step list (step_index, success)

    App->>StackOne: GET /logs/actions/{actionRunId}/steps/{stepIndex}/advanced
    StackOne-->>App: Failed step request/response
```

<Tip>
  Use the [Error Explainer](/connect/troubleshooting#error-explainer) in the StackOne dashboard for AI-generated resolution steps when investigating errors in the request logs UI.
</Tip>

***

## Defender security review

<Warning>
  Defender must be enabled in your [project settings](/secure/defender#configure-from-the-dashboard) before defender log endpoints return scan results.
</Warning>

Review [Defender](/secure/defender) scan results for AI agent tool calls.

1. **List flagged requests**: [List Logs](/platform/api-reference/logs/list-logs) and filter by `risk_level` (returned on log records when Defender is enabled).
2. **Get Defender details**: [Get Action Defender Log](/platform/api-reference/logs/get-action-defender-log) for the full scan output including `risk_level`, `tier2_score`, and classification metadata.
3. **Inspect the response**: [Get Action Advanced Log](/platform/api-reference/logs/get-action-advanced-log) to see the sanitized payload Defender evaluated.

***

## Advanced logs: request and response bodies

[List Logs](/platform/api-reference/logs/list-logs), [Get Action Log](/platform/api-reference/logs/get-action-log), and [Get Step Log](/platform/api-reference/logs/get-step-log) return metadata only. To retrieve full HTTP request and response bodies, use the **advanced** endpoints:

| Scope | Endpoint |
| - | - |
| Entire request | [Get Action Advanced Log](/platform/api-reference/logs/get-action-advanced-log) |
| Single step | [Get Step Advanced Log](/platform/api-reference/logs/get-step-advanced-log) |

<Note>
  Advanced log retention depends on your project's [Advanced Logs](/secure/observability#advanced-logs) settings. Configure retention period and error-only mode in the StackOne dashboard.
</Note>

Fetch advanced logs on demand, not for every row in a high-volume feed.

***

## Related

<CardGroup cols={2}>
  <Card title="Request Log Dashboards" icon="table" href="/features/observability/request-log-dashboards">
    Build admin or customer-facing log dashboards
  </Card>

  <Card title="Observability & Log Sync" icon="chart-line" href="/features/observability/observability-and-log-sync">
    Sync logs to Grafana, Datadog, or custom pipelines
  </Card>

  <Card title="Request Logs (Dashboard)" icon="scroll" href="/connect/troubleshooting">
    View and filter logs in the StackOne dashboard
  </Card>

  <Card title="List Logs API" icon="code" href="/platform/api-reference/logs/list-logs">
    List request logs endpoint reference
  </Card>

  <Card title="Defender" icon="shield" href="/secure/defender">
    Scan AI tool responses for prompt injection
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.