# Get a collection instruction's details

Get a collection instruction with all of its items and their collection windows. Use it to check each item's status, for example when you miss an item_ready_to_charge webhook or to find items that ended as POLICY_EXPIRED, CHARGE_REJECTED, or FAILED (Belvo sends no webhook for these statuses).

The instruction's own status stays PROCESSING until you cancel it, even after every item reaches a final status.

Errors: An instruction_id that doesn't exist or doesn't belong to your organization returns a 500 error. An instruction_id that is not a UUID returns a 404 error.

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

## Path parameters:

  - `instruction_id` (string, required)
    The id of the collection instruction you want to get.
    Example: "c2a6f1d4-7b3e-4f5a-9c8d-1e2f3a4b5c6d"

## Response 200 fields (application/json):

  - `id` (string, required)
    The unique identifier of the collection instruction. Use it to get or cancel the 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"

  - `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"

  - `items` (array, required)
    The items of this instruction. The order of the items is not guaranteed.

  - `items.id` (string, required)
    The unique identifier of the item. Belvo sends it in the item_ready_to_charge webhook, and you use it to cancel the item or mark it as complete.
    Example: "8f14e45f-ceea-4e67-a3f2-2a1b9c3d7e10"

  - `items.amount` (string, required)
    The amount to collect, in BRL, as a decimal string with two decimal places.
    Example: "150.00"

  - `items.external_id` (string,null, required)
    The reference you sent when you created the item. null if you didn't send one.
    Example: "invoice-2026-11-0042"

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

  - PENDING: The item is waiting for its next scheduled balance check. Every new item starts in this status.
  - PROCESSING: A balance check for the item is in progress. After the check, the item returns to PENDING if no account had enough balance and a collection window is still open.
  - CHARGE_SETTLED: One of the user's accounts had enough balance, and Belvo sent you the item_ready_to_charge webhook. Monitoring stops. This status does not mean that a payment was made: you create the Charge yourself, using Payments (Brazil). If Belvo can't deliver the webhook, the item still moves to this status, so also check the instruction's details regularly.
  - POLICY_EXPIRED: All of the item's collection windows ended before any account had enough balance. Belvo does not send a webhook for this status.
  - CHARGE_REJECTED: Belvo could not read the balance of any of the user's accounts (for example, because the data consent is no longer valid). Belvo does not send a webhook for this status.
  - FAILED: An internal error stopped monitoring. Belvo does not send a webhook for this status.
  - COMPLETED: You marked the item as complete (for example, because you collected the amount outside Belvo), so Belvo stopped monitoring it.
  - CANCELLED: You cancelled the item, or the whole collection instruction.

CHARGE_SETTLED, POLICY_EXPIRED, CHARGE_REJECTED, FAILED, COMPLETED, and CANCELLED are final statuses.
    Enum: "PENDING", "PROCESSING", "CHARGE_SETTLED", "POLICY_EXPIRED", "CHARGE_REJECTED", "FAILED", "COMPLETED", "CANCELLED"

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

  - `items.updated_at` (string, required)
    The date and time, in ISO-8601 format (UTC), when Belvo last updated the item. Belvo updates the item at every balance check, so for a PENDING item this is usually the time of its last check.
    Example: "2026-11-04T14:30:12.418230Z"

  - `items.collection_policies` (array, required)
    The collection windows of the item.

  - `items.collection_policies.id` (string, required)
    The unique identifier of the collection window.
    Example: "5d41402a-bc4b-4a76-b971-9d911017c592"

  - `items.collection_policies.start_date` (string, required)
    The first day of the window (YYYY-MM-DD). The window opens at 00:00 UTC on this date.
    Example: "2026-11-05"

  - `items.collection_policies.end_date` (string, required)
    The last day of the window (YYYY-MM-DD), inclusive. The window closes at the end of this date, in UTC.
    Example: "2026-11-10"

  - `items.collection_policies.amount` (string, required)
    The amount you sent for this window, in BRL, as a decimal string. Belvo does not use this value yet; the balance check uses the item's amount.
    Example: "150.00"

  - `items.collection_policies.created_at` (string, required)
    The date and time, in ISO-8601 format (UTC), when Belvo created the window.
    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 404 fields (application/json):

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

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

  - Not found (404)
    Example: "Not found (404)"

  - `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"