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

# Get brokerage account creation status

> Poll GET /apex/accounts/by-request/{request_id} to check brokerage account creation status. Returns ready, pending, or failed states.

Use this endpoint to check the progress of a brokerage account creation that returned a `202` response. Poll until the `status` field is `"ready"` or `"failed"`.

## Path parameters

<ParamField path="request_id" type="string" required>
  The `request_id` you provided when creating the brokerage account.
</ParamField>

## Response

The response always returns HTTP 200 with a `status` field indicating the current state of the request.

### `status: "ready"`

The account was created successfully. The response includes the full account details.

<ResponseField name="status" type="string">
  `"ready"` — the account is ready.
</ResponseField>

<ResponseField name="request_id" type="string">
  The request identifier.
</ResponseField>

<ResponseField name="account" type="object">
  The canonical account record. See [Create brokerage account](/apex/create-account) for field details.
</ResponseField>

<ResponseField name="staging_account" type="object">
  The staging record for the Apex account. See [Create brokerage account](/apex/create-account) for field details.
</ResponseField>

<ResponseField name="staging_person" type="object">
  The staging record for the associated Apex person. See [Create brokerage account](/apex/create-account) for field details.
</ResponseField>

### `status: "pending"`

The account is still being created.

<ResponseField name="status" type="string">
  `"pending"` — creation is in progress.
</ResponseField>

<ResponseField name="request_id" type="string">
  The request identifier.
</ResponseField>

### `status: "failed"`

The account creation failed.

<ResponseField name="status" type="string">
  `"failed"` — creation did not succeed.
</ResponseField>

<ResponseField name="request_id" type="string">
  The request identifier.
</ResponseField>

<ResponseField name="error" type="string">
  A description of why the account creation failed.
</ResponseField>

### Error responses

| Status | Description                                                    |
| ------ | -------------------------------------------------------------- |
| 403    | The brokerage account feature is not enabled for your account. |
| 404    | No account creation request found for the given `request_id`.  |

<RequestExample>
  ```bash cURL theme={null}
  curl https://api.yoshi.ai/apex/accounts/by-request/550e8400-e29b-41d4-a716-446655440000 \
    -H "Authorization: Bearer yoshi_3xK9mP..."
  ```

  ```python Python theme={null}
  import httpx

  response = httpx.get(
      "https://api.yoshi.ai/apex/accounts/by-request/550e8400-e29b-41d4-a716-446655440000",
      headers={"Authorization": "Bearer yoshi_3xK9mP..."},
  )

  data = response.json()
  if data["status"] == "ready":
      print(f"Account ready: {data['account']['id']}")
  elif data["status"] == "failed":
      print(f"Failed: {data['error']}")
  else:
      print("Still pending — try again in a few seconds")
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.yoshi.ai/apex/accounts/by-request/550e8400-e29b-41d4-a716-446655440000",
    {
      headers: { Authorization: "Bearer yoshi_3xK9mP..." },
    }
  );

  const data = await response.json();
  if (data.status === "ready") {
    console.log(`Account ready: ${data.account.id}`);
  } else if (data.status === "failed") {
    console.log(`Failed: ${data.error}`);
  } else {
    console.log("Still pending — try again in a few seconds");
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Ready theme={null}
  {
    "status": "ready",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "account": {
      "id": "acc_brok_abc123",
      "name": "Brokerage Account",
      "type": "investment",
      "subtype": "brokerage",
      "status": "active",
      "external_id": "ext_apex_456",
      "external_source": "apex",
      "apex_account_number": "8AA000001",
      "as_of": "2026-04-15T12:00:00.000Z",
      "created_at": "2026-04-15T12:00:00.000Z",
      "updated_at": "2026-04-15T12:00:00.000Z"
    },
    "staging_account": {
      "id": "stg_abc123",
      "account_number": "8AA000001",
      "apex_person_id": "apx_person_789",
      "apex_state": "COMPLETE",
      "description": "Long-term investments",
      "owner_user_id": "usr_xyz",
      "as_of": "2026-04-15T12:00:00.000Z",
      "created_at": "2026-04-15T12:00:00.000Z",
      "updated_at": "2026-04-15T12:00:00.000Z"
    },
    "staging_person": {
      "id": "stg_person_789",
      "owner_user_id": "usr_xyz",
      "status": "COMPLETE",
      "created_at": "2026-04-15T12:00:00.000Z",
      "updated_at": "2026-04-15T12:00:00.000Z"
    }
  }
  ```

  ```json Pending theme={null}
  {
    "status": "pending",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
  ```

  ```json Failed theme={null}
  {
    "status": "failed",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "error": "Apex account creation failed."
  }
  ```
</ResponseExample>