# Poll an upgrade checkout session (/docs/api-reference/api/v1/auth/upgrade/claim/post)

`POST https://mmb-blurware-alpha.vercel.app/api/v1/auth/upgrade/claim`

Poll an upgrade checkout session

Returns pending until the Stripe webhook lands, then completed with the updated usage summary.

Operation ID: `claimUpgrade`

OpenAPI document: https://mmb-blurware-alpha.vercel.app/openapi.json

## Authentication

Public endpoint; no bearer token is required.

## Request

### Request body — application/json (required)

```json
{
  "type": "object",
  "properties": {
    "sessionId": {
      "type": "string",
      "minLength": 8
    }
  },
  "required": [
    "sessionId"
  ]
}
```

## Responses

### `200` — Current checkout status.

**application/json**

```json
{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "completed"
      ]
    },
    "usage": {
      "allOf": [
        {
          "type": "object",
          "properties": {
            "tenantId": {
              "type": "string"
            },
            "status": {
              "type": "string",
              "enum": [
                "anonymous",
                "claimed",
                "upgraded"
              ]
            },
            "keyPrefix": {
              "type": "string",
              "description": "First characters of the API key, for display."
            },
            "requestsUsed": {
              "type": "number"
            },
            "requestLimit": {
              "type": "number",
              "description": "Lifetime request cap for anonymous keys; tier cap otherwise."
            },
            "dailyRequestsUsed": {
              "type": "number"
            },
            "dailyRequestLimit": {
              "type": "number"
            },
            "expiresAt": {
              "type": "number",
              "description": "Anonymous key expiry, Unix epoch milliseconds."
            },
            "email": {
              "type": "string",
              "description": "Present once the key is claimed."
            }
          },
          "required": [
            "tenantId",
            "status",
            "keyPrefix",
            "requestsUsed",
            "requestLimit",
            "dailyRequestsUsed"
          ]
        },
        {
          "description": "Present once status is completed."
        }
      ]
    }
  },
  "required": [
    "status"
  ]
}
```

### `400` — The body or session ID is invalid.

**application/json**

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "invalid_request"
      ],
      "description": "Stable machine-readable error code."
    },
    "message": {
      "type": "string",
      "description": "Human-readable summary."
    },
    "hint": {
      "type": "string",
      "description": "Endpoint path that resolves this error, when one exists."
    }
  },
  "required": [
    "error",
    "message"
  ]
}
```

### `503` — The gateway is unreachable.

**application/json**

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "enum": [
        "service_unavailable"
      ],
      "description": "Stable machine-readable error code."
    },
    "message": {
      "type": "string",
      "description": "Human-readable summary."
    },
    "hint": {
      "type": "string",
      "description": "Endpoint path that resolves this error, when one exists."
    }
  },
  "required": [
    "error",
    "message"
  ]
}
```