> ## 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 — 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](/guides/request-logs) 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](/api/request-log-dashboards). To export logs into Grafana, Datadog, or a data warehouse, see [Observability & Log Sync](/api/observability-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](/guides/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_ids`                  | Scope to one or more linked accounts (required for customer-facing views) |
| `connector_keys` / `providers` | Filter by integration (e.g. `bamboohr`, `workday`)                        |
| `start_time` / `end_time`      | Time window                                                               |
| `success` / `status_codes`     | Errors only, or specific HTTP statuses                                    |
| `action_ids`                   | 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 '{
        "filter": {
          "start_time": "2024-01-15T00:00:00Z",
          "end_time": "2024-01-15T23:59:59Z",
          "account_ids": ["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={
            "filter": {
                "start_time": "2024-01-15T00:00:00Z",
                "end_time": "2024-01-15T23:59:59Z",
                "account_ids": ["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](/guides/ai-features#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](/guides/defender#configuration) before defender log endpoints return scan results.
</Warning>

Review [Defender](/guides/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](/guides/project-settings#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.

***

## Legacy endpoints

<Warning>
  Only use these endpoints if you are debugging request logs from **legacy unified connectors**. For action-based connectors, use the [drill-down hierarchy](#drill-down-hierarchy) above.
</Warning>

The following endpoints remain available for integrations that generate request logs via legacy unified connectors:

| Legacy endpoint      | Replacement                                                                                                                                               |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /requests/logs` | [List Logs](/platform/api-reference/logs/list-logs) `POST /logs`                                                                                          |
| `/logs/unified/*`    | [List Logs](/platform/api-reference/logs/list-logs) + [Get Action Log](/platform/api-reference/logs/get-action-log)                                       |
| `/logs/provider/*`   | [List Action Step Logs](/platform/api-reference/logs/list-action-step-logs) + [Get Step Advanced Log](/platform/api-reference/logs/get-step-advanced-log) |

***

## Related

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

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

  <Card title="Request Logs (Dashboard)" icon="scroll" href="/guides/request-logs">
    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="/guides/defender">
    Scan AI tool responses for prompt injection
  </Card>
</CardGroup>