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

# List Spending Limits

> Lista todos os limites de gastos do usuário com informações detalhadas de uso atual e validação automática de quota. Para cada limite, calcula automaticamente o valor gasto no período atual, porcentagem de uso, valor restante e status visual. Por padrão retorna apenas limites ativos, mas pode incluir inativos com o parâmetro includeInactive. SEMPRE verifica e retorna informações detalhadas sobre cota do plano (Basic: 0 alertas, Pro: 2 alertas, Premium: 5 alertas) incluindo mensagens formatadas de status e upgrade quando necessário. Requer API key para autenticação e assinatura ativa.

<Note>
  Este endpoint retorna todos os alertas de gastos (spending limits) do usuário autenticado, com informações sobre gastos atuais e status de quota.
</Note>

## Descrição

O endpoint `GET /tools/api/list-spending-limits` retorna a lista completa de alertas de gastos configurados pelo usuário, incluindo o gasto atual de cada período, percentual utilizado e informações sobre a quota disponível no plano do usuário.

## Autenticação

Este endpoint requer autenticação via Bearer token.

<ParamField header="Authorization" type="string" required>
  Bearer token com a API key do usuário. Formato: `Bearer sk-your-api-key-here`
</ParamField>

## Parâmetros de Query

<ParamField query="includeInactive" type="boolean" required="false">
  Se `true`, retorna também os alertas inativos. Por padrão, retorna apenas alertas ativos (`false`).
</ParamField>

<ParamField query="s" type="string" required="false">
  Parâmetro interno para indicar requisições via MCP. Use `s=s` para requisições MCP.
</ParamField>

## Resposta

### Sucesso (200)

<ResponseExample>
  ```json Success theme={null}
  {
    "success": true,
    "data": [
      {
        "id": "limit_123456789",
        "userId": "user_abc123",
        "category": "Alimentação",
        "limitAmount": 1000.00,
        "period": "monthly",
        "isActive": true,
        "isRecurring": true,
        "periodStart": "2024-11-01T00:00:00.000Z",
        "createdAt": "2024-10-15T10:30:00Z",
        "updatedAt": "2024-10-15T10:30:00Z",
        "currentSpending": 450.75,
        "remainingAmount": 549.25,
        "percentageUsed": 45.08,
        "status": "ok"
      },
      {
        "id": "limit_987654321",
        "userId": "user_abc123",
        "category": "Transporte",
        "limitAmount": 500.00,
        "period": "weekly",
        "isActive": true,
        "isRecurring": false,
        "periodStart": "2024-10-28T00:00:00.000Z",
        "createdAt": "2024-10-20T14:00:00Z",
        "updatedAt": "2024-10-20T14:00:00Z",
        "currentSpending": 380.00,
        "remainingAmount": 120.00,
        "percentageUsed": 76.00,
        "status": "warning"
      }
    ],
    "count": 2,
    "quota": {
      "subscriptionType": "pro",
      "currentCount": 2,
      "limit": 10,
      "canCreate": true,
      "remaining": 8,
      "message": "Plano PRO: 2/10 alertas utilizados. Você pode criar mais 8 alertas.",
      "upgradeMessage": null
    },
    "filters": {
      "includeInactive": false
    },
    "timestamp": "2024-11-04T15:30:00Z"
  }
  ```
</ResponseExample>

### Erro de Autenticação (401)

<ResponseExample>
  ```json Error theme={null}
  {
    "error": "Invalid or inactive API key",
    "message": "Please check your API key and try again",
    "type": "invalid_api_key"
  }
  ```
</ResponseExample>

### Erro de Quota Excedida (403)

<ResponseExample>
  ```json Error theme={null}
  {
    "error": "Quota exceeded",
    "message": "Plano FREE: 3/3 alertas utilizados. Limite atingido! Faça upgrade para criar mais alertas.",
    "success": false
  }
  ```
</ResponseExample>

## Campos da Resposta

<ResponseField name="success" type="boolean" required>
  Indica se a requisição foi bem-sucedida
</ResponseField>

<ResponseField name="data" type="array" required>
  Array com os alertas de gastos configurados

  <Expandable title="Spending Limit Object">
    <ResponseField name="id" type="string" required>
      Identificador único do alerta
    </ResponseField>

    <ResponseField name="userId" type="string" required>
      ID do usuário proprietário do alerta
    </ResponseField>

    <ResponseField name="category" type="string" required>
      Categoria de gasto monitorada (ex: "Alimentação", "Transporte")
    </ResponseField>

    <ResponseField name="limitAmount" type="number" required>
      Valor limite configurado em BRL
    </ResponseField>

    <ResponseField name="period" type="string" required>
      Período do alerta: `daily`, `weekly`, `biweekly`, ou `monthly`
    </ResponseField>

    <ResponseField name="isActive" type="boolean" required>
      Se o alerta está ativo
    </ResponseField>

    <ResponseField name="isRecurring" type="boolean" required>
      Se o alerta se renova automaticamente a cada período
    </ResponseField>

    <ResponseField name="periodStart" type="string">
      Data de início do período atual (ISO 8601)
    </ResponseField>

    <ResponseField name="createdAt" type="string" required>
      Data de criação do alerta (ISO 8601)
    </ResponseField>

    <ResponseField name="updatedAt" type="string" required>
      Data da última atualização (ISO 8601)
    </ResponseField>

    <ResponseField name="currentSpending" type="number" required>
      Gasto atual no período
    </ResponseField>

    <ResponseField name="remainingAmount" type="number" required>
      Valor restante até atingir o limite
    </ResponseField>

    <ResponseField name="percentageUsed" type="number" required>
      Percentual do limite já utilizado
    </ResponseField>

    <ResponseField name="status" type="string" required>
      Status do alerta: `ok` (0-49%), `warning` (50-74%), `danger` (75%+)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="count" type="number" required>
  Número total de alertas retornados
</ResponseField>

<ResponseField name="quota" type="object" required>
  Informações sobre a quota de alertas do plano do usuário

  <Expandable title="Quota Object">
    <ResponseField name="subscriptionType" type="string" required>
      Tipo de plano: `free`, `pro`, ou `premium`
    </ResponseField>

    <ResponseField name="currentCount" type="number" required>
      Número de alertas atualmente criados
    </ResponseField>

    <ResponseField name="limit" type="number" required>
      Limite de alertas do plano
    </ResponseField>

    <ResponseField name="canCreate" type="boolean" required>
      Se o usuário pode criar mais alertas
    </ResponseField>

    <ResponseField name="remaining" type="number" required>
      Número de alertas que ainda podem ser criados
    </ResponseField>

    <ResponseField name="message" type="string" required>
      Mensagem descritiva sobre a quota atual
    </ResponseField>

    <ResponseField name="upgradeMessage" type="string">
      Mensagem sugerindo upgrade (se aplicável)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="filters" type="object" required>
  Filtros aplicados na requisição

  <Expandable title="Filters Object">
    <ResponseField name="includeInactive" type="boolean">
      Se alertas inativos foram incluídos
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="timestamp" type="string" required>
  Timestamp da requisição em formato ISO 8601
</ResponseField>

## Exemplos de Uso

### cURL

```bash theme={null}
# Listar todos os alertas ativos
curl -X GET 'https://www.pierre.finance/tools/api/list-spending-limits' \
  -H 'Authorization: Bearer sk-your-api-key-here'

# Listar todos os alertas (incluindo inativos)
curl -X GET 'https://www.pierre.finance/tools/api/list-spending-limits?includeInactive=true' \
  -H 'Authorization: Bearer sk-your-api-key-here'
```

### JavaScript

```javascript theme={null}
const API_KEY = 'sk-your-api-key-here';
const BASE_URL = 'https://www.pierre.finance/tools/api';

async function listSpendingLimits(includeInactive = false) {
  const params = new URLSearchParams({ includeInactive });
  const response = await fetch(`${BASE_URL}/list-spending-limits?${params}`, {
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    }
  });
  
  return await response.json();
}

// Exemplos de uso
listSpendingLimits(); // Apenas alertas ativos
listSpendingLimits(true); // Incluindo inativos
```

### Python

```python theme={null}
import requests

API_KEY = 'sk-your-api-key-here'
BASE_URL = 'https://www.pierre.finance/tools/api'

headers = {
    'Authorization': f'Bearer {API_KEY}',
    'Content-Type': 'application/json'
}

def list_spending_limits(include_inactive=False):
    params = {'includeInactive': str(include_inactive).lower()}
    response = requests.get(f'{BASE_URL}/list-spending-limits', 
                          headers=headers, params=params)
    return response.json()

# Exemplos de uso
limits = list_spending_limits()  # Apenas ativos
all_limits = list_spending_limits(include_inactive=True)  # Todos
```

## Códigos de Status

* `200`: Sucesso - Alertas retornados
* `401`: Erro de autenticação ou assinatura
* `403`: Quota excedida (ao tentar criar novos alertas)
* `500`: Erro interno do servidor

## Limites por Plano

* **FREE**: 3 alertas de gastos
* **PRO**: 10 alertas de gastos
* **PREMIUM**: 30 alertas de gastos

<Note>
  Os alertas são calculados em tempo real com base nas transações do período especificado. O status é atualizado automaticamente: `ok` para 0-49%, `warning` para 50-74%, e `danger` para 75% ou mais do limite.
</Note>


## OpenAPI

````yaml GET /tools/api/list-spending-limits
openapi: 3.1.0
info:
  title: Pierre Finance API
  description: >-
    API para acessar dados financeiros do Pierre Finance, incluindo contas,
    transações, parcelas e sincronização.
  version: v1.0.0
servers:
  - url: https://www.pierre.finance
security: []
tags:
  - name: Authentication
    description: API key management and authentication
  - name: Accounts
    description: Financial accounts management
  - name: Transactions
    description: Financial transactions
  - name: Installments
    description: Credit card installments and purchases
  - name: Bills
    description: Credit card bills and current bill summaries
  - name: Balance
    description: Account balance information
  - name: Closing Dates
    description: Credit card closing date management
  - name: Sync
    description: Account synchronization
  - name: Spending Limits
    description: Personal spending limits and alerts management
  - name: Payment Reminders
    description: Payment reminders management with WhatsApp and Email notifications
  - name: Analytics
    description: Financial analytics and insights
  - name: Memories
    description: User memory management for personalized AI interactions
  - name: Open Finance
    description: Open Finance connection and integration
paths:
  /tools/api/list-spending-limits:
    get:
      tags:
        - Spending Limits
      description: >-
        Lista todos os limites de gastos do usuário com informações detalhadas
        de uso atual e validação automática de quota. Para cada limite, calcula
        automaticamente o valor gasto no período atual, porcentagem de uso,
        valor restante e status visual. Por padrão retorna apenas limites
        ativos, mas pode incluir inativos com o parâmetro includeInactive.
        SEMPRE verifica e retorna informações detalhadas sobre cota do plano
        (Basic: 0 alertas, Pro: 2 alertas, Premium: 5 alertas) incluindo
        mensagens formatadas de status e upgrade quando necessário. Requer API
        key para autenticação e assinatura ativa.
      operationId: listSpendingLimits
      parameters:
        - name: includeInactive
          in: query
          description: Se deve incluir limites inativos na resposta
          required: false
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Lista de limites de gastos
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SpendingLimitWithUsage'
                  count:
                    type: number
                    description: Número de limites retornados
                    example: 3
                  quota:
                    $ref: '#/components/schemas/SpendingLimitQuota'
                  filters:
                    type: object
                    properties:
                      includeInactive:
                        type: boolean
                  timestamp:
                    type: string
                    format: date-time
        '401':
          $ref: '#/components/responses/AuthError'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - BearerAuth: []
components:
  schemas:
    SpendingLimitWithUsage: {}
    SpendingLimitQuota: {}
    AuthError: {}
    ServerError: {}
  responses:
    AuthError:
      description: Authentication or subscription error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AuthError'
    ServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ServerError'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: string
      description: 'API key in Bearer token format. Example: Bearer sk-your-api-key-here'

````