# List collection instructions

List the collection instructions of your organization. The response is an array of summaries without the items. To see the items and their statuses, get the instruction's details.

The response is not paginated: it returns every instruction that matches your filters, in no guaranteed order. Use status, consent_id, created_after, and created_before to keep the response small. Belvo ignores any other query parameter.

Errors: A filter value that is not valid (for example, an unknown status or a date that is not YYYY-MM-DD) returns a 500 error.

Endpoint: GET /api/collection-instructions/
Version: 1.223.0
Security: basicAuth

## Query parameters:

  - `status` (string)
    Return only collection instructions with this status.
    Enum: "PROCESSING", "COMPLETED", "CANCELLED"

  - `consent_id` (string)
    Return only collection instructions for this data consent. Use the consent_id value from a previous list response.
    Example: "0b7c3f2e-9a41-4d8b-8e6f-3c2d1a5b7e90"

  - `created_after` (string)
    Return only collection instructions created on or after this date (YYYY-MM-DD), from 00:00 UTC.
    Example: "2026-11-01"

  - `created_before` (string)
    Return only collection instructions created before this date (YYYY-MM-DD). The date itself is excluded; the filter stops at 00:00 UTC on this date.
    Example: "2026-12-01"

## Response 200 fields (application/json):

  - `id` (string, required)
    O identificador único da instrução de coleta.
    Example: "c2a6f1d4-7b3e-4f5a-9c8d-1e2f3a4b5c6d"

  - `link_id` (string, required)
    The link.id whose accounts Belvo monitors for this instruction.
    Example: "3b979abb-fd60-4d15-a655-8f462ca4ea8f"

  - `consent_id` (string,null, required)
    The ID of the Open Finance data consent that Belvo found for the Link when you created the instruction. You can use this value in the consent_id filter.
    Example: "0b7c3f2e-9a41-4d8b-8e6f-3c2d1a5b7e90"

  - `status` (string, required)
    The status of the collection instruction. Can be one of:

  - PROCESSING: The instruction was created. It stays in this status until you cancel it, even after every item has reached a final status. Check each item's status to see how monitoring ended.
  - COMPLETED: Reserved for future use. Belvo does not currently set this status.
  - CANCELLED: You cancelled the instruction. Any items that were still PENDING or PROCESSING were cancelled too.
    Enum: "PROCESSING", "COMPLETED", "CANCELLED"

  - `created_at` (string, required)
    The date and time, in ISO-8601 format (UTC), when Belvo created the instruction.
    Example: "2026-11-04T14:30:12.418230Z"

  - `updated_at` (string, required)
    The date and time, in ISO-8601 format (UTC), when the instruction's status last changed.
    Example: "2026-11-04T14:30:12.418230Z"

## Response 403 fields (application/json):

  - `code` (string)
    A unique error code (permission_denied) that allows you to classify and handle the error programmatically.
    Example: "permission_denied"

  - `message` (string)
    A short description of the error. For permission_denied errors, the description is:

  - You do not have permission to perform this action.
    Example: "You do not have permission to perform this action."

  - `request_id` (string)
    Um ID único de 32 caracteres da solicitação (correspondente a um padrão regex de: [a-f0-9]{32}). Forneça este ID ao entrar em contato com a equipe de suporte da Belvo para acelerar as investigações.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 408 fields (application/json):

  - `code` (string)
    Um código de erro único (request_timeout) que permite classificar e lidar com o erro programaticamente.

ℹ️ Consulte nosso DevPortal para mais informações sobre como lidar com erros 408 request_timeout.
    Example: "request_timeout"

  - `message` (string)
    Uma breve descrição do erro.

Para erros de request_timeout, a descrição é:

  - The request timed out, you can retry asking for less data by changing your query parameters.
    Example: "The request timed out, you can retry asking for less data by changing your query parameters"

  - `request_id` (string)
    Um ID único de 32 caracteres da solicitação (correspondente a um padrão regex de: [a-f0-9]{32}). Forneça este ID ao entrar em contato com a equipe de suporte da Belvo para acelerar as investigações.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 500 fields (application/json):

  - `code` (string)
    A unique error code (server_error) that allows you to classify and handle the error programmatically.
    Example: "server_error"

  - `message` (string)
    A short description of the error. For server_error errors, the description is:

  - Server error (500)
    Example: "Server error (500)"

  - `request_id` (string)
    Um ID único de 32 caracteres da solicitação (correspondente a um padrão regex de: [a-f0-9]{32}). Forneça este ID ao entrar em contato com a equipe de suporte da Belvo para acelerar as investigações.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"