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

# Request stats

> Counts per time bucket (2xx, 4xx, 5xx, total) for the same filters as the list. Empty buckets are returned as zeros.

Returns request counts over time, split into successful, client-error and server-error responses, for the same filters you use to list request logs.

> Same auth as the list: an API key with `read:request-logs`, or a session of an owner or admin with `X-Organization-Id`.

## Query Parameters

Same filters as [List Request Logs](https://docs.timbrix.mx/api-reference/request-logs/list.md), without `cursor` and `limit`.

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `from` | string (ISO 8601) | No | 24 hours before `to` | Start of the range |
| `to` | string (ISO 8601) | No | now | End of the range. The maximum range is 30 days; an invalid range returns `400` |
| `status` | string | No | — | Comma-separated list of classes (`2xx`, `4xx`, `5xx`) and exact codes, OR-ed. Up to 20. A single value works as before |
| `method` | string | No | — | Comma-separated list of `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, OR-ed |
| `q` | string | No | — | Case-insensitive *contains* search on the real request path. 1–200 characters; `%` and `_` match literally |
| `route` | string | No | — | Route template, e.g. `/invoices/:uuid` |
| `apiKeyId` | string (uuid) | No | — | Only requests made with this API key |
| `environment` | `"sandbox"` \| `"production"` | No | — | Filter by environment |
| `channel` | `"web"` \| `"api"` \| `"sdk"` \| `"cli"` \| `"mcp"` | No | — | Filter by the channel the request came from |
| `authFailure` | string | No | — | `any` for every rejected request, or one of `inactive`, `expired`, `ip_not_allowed`, `missing_scope` |
| `minDurationMs` | integer | No | — | Lower latency bound in milliseconds (0–600000). Greater than `maxDurationMs` returns `400` |
| `maxDurationMs` | integer | No | — | Upper latency bound in milliseconds (0–600000) |

## Bucket size

The bucket size depends on the length of the range:

| Range | Bucket size |
| - | - |
| 1 h | 1 min |
| 24 h | 15 min |
| 7 d | 60 min |
| 30 d | 360 min |

The rule: the smallest of 1, 5, 15, 60, 360 minutes that yields at most 200 buckets. Buckets are aligned to UTC and empty ones are returned as zeros.

## Example Request

```bash theme={null}
curl "https://api.timbrix.mx/request-logs/stats?status=4xx,5xx" \
  -H "X-API-Key: sk_..."
```

```typescript theme={null}
import { Timbrix } from "@timbrix/sdk"

const client = new Timbrix({ apiKey: "sk_..." })

const stats = await client.requestLogs.stats({ status: ["4xx", "5xx"] })
console.log(stats.bucketMinutes, stats.buckets)
```

With a session, pass the organization as the second argument:

```typescript theme={null}
const stats = await client.requestLogs.stats(
  { status: ["4xx", "5xx"] },
  "550e8400-e29b-41d4-a716-446655440000"
)
```

## Example Response

```json theme={null}
{
  "from": "2026-10-13T17:00:00.000Z",
  "to": "2026-10-20T17:00:00.000Z",
  "bucketMinutes": 60,
  "buckets": [
    {
      "start": "2026-10-13T17:00:00.000Z",
      "total": 12,
      "ok": 10,
      "clientError": 2,
      "serverError": 0
    }
  ]
}
```

## Common Errors

### 400 Bad Request

Invalid `from`/`to` range (or more than 30 days), a filter with an unsupported value, or `minDurationMs` greater than `maxDurationMs`. Also returned when `X-Organization-Id` is missing on a session-authenticated request.

### 401 Unauthorized

Missing or invalid Bearer token / API key.

### 403 Forbidden

The authenticated user is not an owner or admin of the organization, or the API key does not have the `read:request-logs` scope.


## OpenAPI

````yaml GET /request-logs/stats
openapi: 3.0.0
info:
  title: Timbrix API
  description: >-
    API de facturación electrónica CFDI 4.0 para México, con servidor OAuth2
    para gestionar organizaciones, miembros y webhooks. Compatible con agentes
    de IA — ver la extensión `x-ai-agent-friendly` en la raíz de esta spec.


    REST API with OAuth2 server for managing organizations, members, and
    webhooks.
  version: '1.0'
  contact: {}
servers: []
security: []
tags:
  - name: organizations
    description: Organization management endpoints
  - name: oauth
    description: OAuth2 authentication and authorization
  - name: webhooks
    description: Webhook configuration and delivery
  - name: users
    description: User information endpoints
  - name: api-keys
    description: API Keys management and validation
  - name: request-logs
    description: API request log
paths:
  /request-logs/stats:
    get:
      tags:
        - request-logs
      summary: Request counts over time
      description: >-
        Counts per time bucket (2xx, 4xx, 5xx, total) for the same filters as
        the list. Empty buckets are returned as zeros.
      operationId: RequestLogsController_stats
      parameters:
        - name: from
          required: false
          in: query
          description: 'Inicio (ISO 8601). Default: to - 24 h'
          schema:
            type: string
        - name: to
          required: false
          in: query
          description: 'Fin (ISO 8601). Default: ahora'
          schema:
            type: string
        - name: status
          required: false
          in: query
          description: >-
            Lista separada por comas de clases (2xx, 4xx, 5xx) y códigos
            exactos. Hasta 20.
          schema:
            example: 4xx,500
            type: string
        - name: method
          required: false
          in: query
          description: Lista separada por comas de GET, POST, PUT, PATCH, DELETE.
          schema:
            example: GET,POST
            type: string
        - name: q
          required: false
          in: query
          description: Busca en el path real (contiene, sin distinguir mayúsculas).
          schema:
            example: /invoices
            type: string
        - name: route
          required: false
          in: query
          schema:
            type: string
            example: /invoices/:uuid
        - name: apiKeyId
          required: false
          in: query
          schema:
            type: string
        - name: environment
          required: false
          in: query
          schema:
            type: string
            enum:
              - sandbox
              - production
        - name: channel
          required: false
          in: query
          schema:
            type: string
            enum:
              - web
              - api
              - sdk
              - cli
              - mcp
        - name: authFailure
          required: false
          in: query
          schema:
            type: string
            enum:
              - any
              - inactive
              - expired
              - ip_not_allowed
              - missing_scope
        - name: minDurationMs
          required: false
          in: query
          schema:
            minimum: 0
            maximum: 600000
            type: number
        - name: maxDurationMs
          required: false
          in: query
          schema:
            minimum: 0
            maximum: 600000
            type: number
        - name: X-Organization-Id
          in: header
          description: >-
            Required for Supabase session auth (owner or admin). Ignored with an
            API key.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestLogStatsResponseDto'
      security:
        - apiKey: []
        - bearer: []
components:
  schemas:
    RequestLogStatsResponseDto:
      type: object
      properties:
        from:
          type: string
          example: '2026-10-13T17:00:00.000Z'
        to:
          type: string
          example: '2026-10-20T17:00:00.000Z'
        bucketMinutes:
          type: number
          example: 60
          enum:
            - 1
            - 5
            - 15
            - 60
            - 360
        buckets:
          type: array
          items:
            $ref: '#/components/schemas/RequestLogStatsBucketDto'
      required:
        - from
        - to
        - bucketMinutes
        - buckets
    RequestLogStatsBucketDto:
      type: object
      properties:
        start:
          type: string
          example: '2026-10-13T17:00:00.000Z'
        total:
          type: number
          example: 12
        ok:
          type: number
          example: 10
          description: Status 200–299
        clientError:
          type: number
          example: 2
          description: Status 400–499
        serverError:
          type: number
          example: 0
          description: Status 500–599
      required:
        - start
        - total
        - ok
        - clientError
        - serverError
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'API Key for authentication (format: sk_...)'
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http

````

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