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

# Retrieve Session

export const ParamList = ({items = [], is_child = false}) => {
  return items.map(item => {
    const field_props = {
      id: Math.random().toString(),
      body: item.name,
      name: item.name,
      type: item.type,
      required: item.required
    };
    const enums = item.enums || [];
    const items = item.items || [];
    const has_items = items?.length > 0;
    const has_enums = enums?.length > 0;
    const should_default_open = item.defaultOpen || false;
    const render_child_item = () => {
      const child_props = {
        title: has_enums ? "Possible enum values" : "properties"
      };
      if (should_default_open) child_props.defaultOpen = true;
      const has_inline_enums = has_enums && enums.every(enum_item => typeof enum_item === 'string') && enums.map((enum_item, idx) => {
        const is_last = idx === enums.length - 1;
        const is_2nd_to_last = idx === enums.length - 2;
        return <>
            <code>{enum_item}</code>
            {is_last && ''}
            {is_2nd_to_last && ' or '}
            {!is_last && !is_2nd_to_last && ', '}
          </>;
      });
      const enum_list = has_enums && !has_inline_enums && <Accordion {...child_props}>
          {enums.map((enum_item, index) => <div key={`enum-${index}`}>
              <code>{enum_item.name}</code>
              <br />
              <p>{enum_item.description}</p>
            </div>)}
        </Accordion>;
      const item_list = has_items && <Expandable {...child_props}>
          <ParamList items={items || []} is_child />
        </Expandable>;
      return <>
          <p>
            {item.description}
            {has_inline_enums && [has_inline_enums.length > 1 ? ' One of ' : ' Must be ', ...has_inline_enums]}
          </p>

          {enum_list}
          {item_list}
        </>;
    };
    return is_child ? <ResponseField {...field_props}>{render_child_item()}</ResponseField> : <ParamField {...field_props}>{render_child_item()}</ParamField>;
  });
};

Retrieve the current state of an Opal session. Use this endpoint from your backend to check a user's progress, such as the confirmed allocations and payout status of a [Balance Transfer](/opal/balance_transfer/overview) session.

<Note>
  This endpoint requires your secret API key. Requests authenticated with an
  Opal token are rejected. Sessions that do not belong to your team return
  `404`.
</Note>

## Path Parameters

<ParamList
  items={[
{
  name: "session_id",
  type: "string",
  required: true,
  description: "ID of the Opal session, returned when you create a token.",
},
]}
/>

## Returns

Returns the Opal session. The session includes a flow object for each flow in its mode (`idv`, `cxn`, `avf`, `txn`, or `bt`). Flows that are not part of the mode are `null`.

<ParamList
  items={[
{
  name: "id",
  type: "string",
  description: "Unique identifier for the session.",
},
{
  name: "mode",
  type: "enum",
  description: "The mode the session was created with.",
  enums: [
    "identity_verification",
    "connect",
    "card_connect",
    "account_verification",
    "transactions",
    "balance_transfer",
  ],
},
{
  name: "entity",
  type: "object",
  description: "The Entity the session belongs to, including its verification status.",
},
{
  name: "bt",
  type: "object | null",
  description: (
    <>
      The balance transfer flow. Present only when <code>mode</code> is{" "}
      <code>balance_transfer</code>. All monetary values are in cents.
    </>
  ),
  items: [
    {
      name: "bt.loan_amount",
      type: "number",
      description: "The approved loan amount provided at token creation.",
    },
    {
      name: "bt.minimum_payment",
      type: "number",
      description: "The minimum amount that can be allocated to a single account.",
    },
    {
      name: "bt.maximum_payment",
      type: "number",
      description: "The maximum amount that can be allocated to a single account.",
    },
    {
      name: "bt.residual_amount_max",
      type: "number | null",
      description:
        "The maximum amount of the loan that can remain unallocated. null means any unallocated amount is allowed.",
    },
    {
      name: "bt.allocations",
      type: "object",
      description:
        "A map of account ID to the amount allocated to that account. Populated when the user confirms.",
    },
    {
      name: "bt.payout_status",
      type: "enum",
      description: "The payout status of the balance transfer.",
      enums: [
        {
          name: "pending_amounts",
          description: "The user has not confirmed allocations yet.",
        },
        {
          name: "pending_release",
          description:
            "The user confirmed allocations. Method is waiting for your backend to release payments.",
        },
        {
          name: "released",
          description: "Your backend released the payments.",
        },
      ],
    },
    {
      name: "bt.payment_ids",
      type: "object",
      description:
        "A map of account ID to the ID of the Payment created for that account. A null value means the payment could not be created. Empty until payments are released.",
    },
    {
      name: "bt.released_at",
      type: "string | null",
      description: "Timestamp of when payments were released.",
    },
    {
      name: "bt.completed",
      type: "boolean",
      description: "Whether the user confirmed their allocations.",
    },
  ],
},
{
  name: "created_at",
  type: "string",
  description: "Timestamp of when the session was created.",
},
{
  name: "updated_at",
  type: "string",
  description: "Timestamp of when the session was last updated.",
},
]}
/>

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/opal/sessions/osess_zde3mW34pEHqV \
    -H "Method-Version: 2025-07-04" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": {
      "id": "osess_zde3mW34pEHqV",
      "mode": "balance_transfer",
      "bt": {
        "loan_amount": 1000000,
        "minimum_payment": 5000,
        "maximum_payment": 500000,
        "residual_amount_max": 150000,
        "allocations": {
          "acc_hmap9mbgfLcf9": 500000,
          "acc_YXDrjADGjC76U": 350000
        },
        "payout_status": "pending_release",
        "payment_ids": {},
        "released_at": null,
        "completed": true
      },
      "created_at": "2026-09-23T22:31:40.312Z",
      "updated_at": "2026-09-23T22:48:10.512Z"
    },
    "message": null
  }
  ```
</ResponseExample>