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

# Requests

> Manage and analyze API requests captured by ApiTraffic

## List Requests

<api-endpoint method="GET" url="https://api.apitraffic.io/v1/accounts/{accountSid}/buckets/{bucketSid}/requests" />

Retrieve all requests captured in a specific bucket.

### Path Parameters

<ParamField path="accountSid" type="string" required>
  Account identifier (format: `acc_` followed by 27 alphanumeric characters)
</ParamField>

<ParamField path="bucketSid" type="string" required>
  Bucket identifier
</ParamField>

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication
</ParamField>

### Response

<ResponseField name="hasMore" type="boolean">
  Indicates if there are more records to paginate through
</ResponseField>

<ResponseField name="records" type="array">
  <Expandable title="Request Objects">
    <ResponseField name="sid" type="string">
      Request identifier (format: `req_` followed by 27 alphanumeric characters)
    </ResponseField>

    <ResponseField name="bucketSid" type="string">
      Bucket identifier this request belongs to
    </ResponseField>

    <ResponseField name="environmentSid" type="string">
      Environment identifier (6 character alphanumeric, nullable)
    </ResponseField>

    <ResponseField name="contextSid" type="string">
      Request context identifier (nullable)
    </ResponseField>

    <ResponseField name="direction" type="string">
      Request direction: `in` (inbound) or `out` (outbound)
    </ResponseField>

    <ResponseField name="note" type="string">
      User-added notes for the request (nullable)
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 timestamp when request was created
    </ResponseField>

    <ResponseField name="receivedAt" type="string">
      ISO 8601 timestamp when request was received
    </ResponseField>

    <ResponseField name="firewall" type="object">
      <Expandable title="Firewall Information">
        <ResponseField name="blocked" type="boolean">
          Whether the request was blocked by firewall rules
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="request" type="object">
      <Expandable title="Request Details">
        <ResponseField name="host" type="string">
          Request host (nullable)
        </ResponseField>

        <ResponseField name="method" type="string">
          HTTP method (nullable)
        </ResponseField>

        <ResponseField name="path" type="string">
          Request path (nullable)
        </ResponseField>

        <ResponseField name="port" type="number">
          Request port (nullable)
        </ResponseField>

        <ResponseField name="url" type="string">
          Full request URL (nullable)
        </ResponseField>

        <ResponseField name="queryString" type="object">
          Query string parameters
        </ResponseField>

        <ResponseField name="headers" type="object">
          Request headers as key-value pairs
        </ResponseField>

        <ResponseField name="body" type="any">
          Request body content
        </ResponseField>

        <ResponseField name="contentType" type="string">
          Content type of the request (nullable)
        </ResponseField>

        <ResponseField name="size" type="number">
          Size of request payload in bytes (nullable)
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="response" type="object">
      <Expandable title="Response Details">
        <ResponseField name="statusCode" type="number">
          HTTP status code returned (nullable)
        </ResponseField>

        <ResponseField name="headers" type="object">
          Response headers as key-value pairs (nullable)
        </ResponseField>

        <ResponseField name="size" type="number">
          Size of response payload in bytes (nullable)
        </ResponseField>

        <ResponseField name="body" type="any">
          Response body content
        </ResponseField>

        <ResponseField name="contentType" type="string">
          Content type of the response (nullable)
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="timings" type="object">
      <Expandable title="Performance Timings">
        <ResponseField name="duration" type="number">
          Total request duration in milliseconds (nullable)
        </ResponseField>

        <ResponseField name="start" type="number">
          Request start time (nullable)
        </ResponseField>

        <ResponseField name="end" type="number">
          Request end time (nullable)
        </ResponseField>

        <ResponseField name="lookup" type="number">
          DNS lookup time (nullable)
        </ResponseField>

        <ResponseField name="socket" type="number">
          Socket assignment time (nullable)
        </ResponseField>

        <ResponseField name="upload" type="number">
          Upload completion time (nullable)
        </ResponseField>

        <ResponseField name="connect" type="number">
          Connection establishment time (nullable)
        </ResponseField>

        <ResponseField name="response" type="number">
          Response start time (nullable)
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.apitraffic.io/v1/accounts/acc_abc123def456ghi789jkl012/buckets/bkt_xyz789uvw012rst345abc/requests" \
    -H "Authorization: Bearer your-jwt-token"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.apitraffic.io/v1/accounts/acc_abc123def456ghi789jkl012/buckets/bkt_xyz789uvw012rst345abc/requests', {
    headers: {
      'Authorization': 'Bearer your-jwt-token'
    }
  });

  const requests = await response.json();
  console.log(requests);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.apitraffic.io/v1/accounts/acc_abc123def456ghi789jkl012/buckets/bkt_xyz789uvw012rst345abc/requests',
      headers={'Authorization': 'Bearer your-jwt-token'}
  )

  requests_data = response.json()
  print(requests_data)
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "hasMore": false,
    "records": [
      {
        "sid": "req_abc123def456ghi789jkl012mno",
        "bucketSid": "bkt_xyz789uvw012rst345abc",
        "environmentSid": "env123",
        "contextSid": null,
        "direction": "in",
        "note": null,
        "createdAt": "2023-12-01T10:30:00.000Z",
        "receivedAt": "2023-12-01T10:30:00.100Z",
        "firewall": {
          "blocked": false
        },
        "request": {
          "host": "api.example.com",
          "method": "GET",
          "path": "/users/123",
          "port": 443,
          "url": "https://api.example.com/users/123",
          "queryString": {},
          "headers": {
            "user-agent": "Mozilla/5.0",
            "accept": "application/json"
          },
          "body": null,
          "contentType": null,
          "size": 0
        },
        "response": {
          "statusCode": 200,
          "headers": {
            "content-type": "application/json",
            "content-length": "156"
          },
          "size": 156,
          "body": {
            "id": 123,
            "name": "John Doe",
            "email": "john@example.com"
          },
          "contentType": "application/json"
        },
        "timings": {
          "duration": 245,
          "start": 1701423000000,
          "end": 1701423000245,
          "lookup": 12,
          "socket": 25,
          "upload": 30,
          "connect": 45,
          "response": 200
        }
      }
    ]
  }
  ```
</ResponseExample>

***

## Get Request

<api-endpoint method="GET" url="https://api.apitraffic.io/v1/accounts/{accountSid}/buckets/{bucketSid}/requests/{requestSid}" />

Retrieve details of a specific request.

### Path Parameters

<ParamField path="accountSid" type="string" required>
  Account identifier
</ParamField>

<ParamField path="bucketSid" type="string" required>
  Bucket identifier
</ParamField>

<ParamField path="requestSid" type="string" required>
  Request identifier
</ParamField>

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication
</ParamField>

### Response

Returns a single request object with the same structure as described in the List Requests response.

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.apitraffic.io/v1/accounts/acc_abc123def456ghi789jkl012/buckets/bkt_xyz789uvw012rst345abc/requests/req_abc123def456ghi789jkl012mno" \
    -H "Authorization: Bearer your-jwt-token"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.apitraffic.io/v1/accounts/acc_abc123def456ghi789jkl012/buckets/bkt_xyz789uvw012rst345abc/requests/req_abc123def456ghi789jkl012mno', {
    headers: {
      'Authorization': 'Bearer your-jwt-token'
    }
  });

  const request = await response.json();
  console.log(request);
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "sid": "req_abc123def456ghi789jkl012mno",
    "bucketSid": "bkt_xyz789uvw012rst345abc",
    "environmentSid": "env123",
    "contextSid": null,
    "direction": "in",
    "note": null,
    "createdAt": "2023-12-01T10:30:00.000Z",
    "receivedAt": "2023-12-01T10:30:00.100Z",
    "firewall": {
      "blocked": false
    },
    "request": {
      "host": "api.example.com",
      "method": "GET",
      "path": "/users/123",
      "port": 443,
      "url": "https://api.example.com/users/123",
      "queryString": {},
      "headers": {
        "user-agent": "Mozilla/5.0",
        "accept": "application/json"
      },
      "body": null,
      "contentType": null,
      "size": 0
    },
    "response": {
      "statusCode": 200,
      "headers": {
        "content-type": "application/json",
        "content-length": "156"
      },
      "size": 156,
      "body": {
        "id": 123,
        "name": "John Doe",
        "email": "john@example.com"
      },
      "contentType": "application/json"
    },
    "timings": {
      "duration": 245,
      "start": 1701423000000,
      "end": 1701423000245,
      "lookup": 12,
      "socket": 25,
      "upload": 30,
      "connect": 45,
      "response": 200
    }
  }
  ```
</ResponseExample>

***

## Update Request

<api-endpoint method="PUT" url="https://api.apitraffic.io/v1/accounts/{accountSid}/buckets/{bucketSid}/requests/{requestSid}" />

Update details of a specific request (typically used to add notes or modify metadata).

### Path Parameters

<ParamField path="accountSid" type="string" required>
  Account identifier
</ParamField>

<ParamField path="bucketSid" type="string" required>
  Bucket identifier
</ParamField>

<ParamField path="requestSid" type="string" required>
  Request identifier
</ParamField>

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication
</ParamField>

### Request Body

<ParamField body="note" type="string">
  Add or update notes for the request
</ParamField>

### Response

Returns the updated request object.

<RequestExample>
  ```bash cURL theme={null}
  curl -X PUT "https://api.apitraffic.io/v1/accounts/acc_abc123def456ghi789jkl012/buckets/bkt_xyz789uvw012rst345abc/requests/req_abc123def456ghi789jkl012mno" \
    -H "Authorization: Bearer your-jwt-token" \
    -H "Content-Type: application/json" \
    -d '{
      "note": "This request was flagged for review"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.apitraffic.io/v1/accounts/acc_abc123def456ghi789jkl012/buckets/bkt_xyz789uvw012rst345abc/requests/req_abc123def456ghi789jkl012mno', {
    method: 'PUT',
    headers: {
      'Authorization': 'Bearer your-jwt-token',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      note: 'This request was flagged for review'
    })
  });

  const request = await response.json();
  console.log(request);
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "sid": "req_abc123def456ghi789jkl012mno",
    "bucketSid": "bkt_xyz789uvw012rst345abc",
    "environmentSid": "env123",
    "contextSid": null,
    "direction": "in",
    "note": "This request was flagged for review",
    "createdAt": "2023-12-01T10:30:00.000Z",
    "receivedAt": "2023-12-01T10:30:00.100Z",
    "firewall": {
      "blocked": false
    },
    "request": {
      "host": "api.example.com",
      "method": "GET",
      "path": "/users/123",
      "port": 443,
      "url": "https://api.example.com/users/123",
      "queryString": {},
      "headers": {
        "user-agent": "Mozilla/5.0",
        "accept": "application/json"
      },
      "body": null,
      "contentType": null,
      "size": 0
    },
    "response": {
      "statusCode": 200,
      "headers": {
        "content-type": "application/json",
        "content-length": "156"
      },
      "size": 156,
      "body": {
        "id": 123,
        "name": "John Doe",
        "email": "john@example.com"
      },
      "contentType": "application/json"
    },
    "timings": {
      "duration": 245,
      "start": 1701423000000,
      "end": 1701423000245,
      "lookup": 12,
      "socket": 25,
      "upload": 30,
      "connect": 45,
      "response": 200
    }
  }
  ```
</ResponseExample>

***

## Delete Request

<api-endpoint method="DELETE" url="https://api.apitraffic.io/v1/accounts/{accountSid}/buckets/{bucketSid}/requests/{requestSid}" />

Delete a specific request from the bucket.

<Warning>
  This action is irreversible. The request data will be permanently deleted.
</Warning>

### Path Parameters

<ParamField path="accountSid" type="string" required>
  Account identifier
</ParamField>

<ParamField path="bucketSid" type="string" required>
  Bucket identifier
</ParamField>

<ParamField path="requestSid" type="string" required>
  Request identifier
</ParamField>

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication
</ParamField>

### Response

<ResponseField name="sid" type="string">
  ID of the deleted request
</ResponseField>

<ResponseField name="deleted" type="boolean">
  Flag indicating the request was successfully deleted
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X DELETE "https://api.apitraffic.io/v1/accounts/acc_abc123def456ghi789jkl012/buckets/bkt_xyz789uvw012rst345abc/requests/req_abc123def456ghi789jkl012mno" \
    -H "Authorization: Bearer your-jwt-token"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.apitraffic.io/v1/accounts/acc_abc123def456ghi789jkl012/buckets/bkt_xyz789uvw012rst345abc/requests/req_abc123def456ghi789jkl012mno', {
    method: 'DELETE',
    headers: {
      'Authorization': 'Bearer your-jwt-token'
    }
  });

  const result = await response.json();
  console.log(result);
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "sid": "req_abc123def456ghi789jkl012mno",
    "deleted": true
  }
  ```
</ResponseExample>