# 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)
    The unique identifier of the collection instruction.
    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)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 408 fields (application/json):

  - `code` (string)
    A unique error code (request_timeout) that allows you to classify and handle the error programmatically.


ℹ️ Check our DevPortal for more information on how to handle 408 request_timeout errors.
    Example: "request_timeout"

  - `message` (string)
    A short description of the error. 


For request_timeout errors, the description is:
  
  - 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)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    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)
    A 32-character unique ID of the request (matching a regex pattern of: [a-f0-9]{32}). Provide this ID when contacting the Belvo support team to accelerate investigations.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"