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

# Get Line Request

> Fetch the current status of a line request. REST endpoint in the Tuco AI iMessage API — bearer-token auth, JSON request/response, full schema and code examples.

<Note>
  Use this endpoint to poll a specific line request after creation. It is the source of truth for whether the request is still waiting for payment, already provisioning, active, failed, or canceled.
</Note>

## When To Use This Endpoint

Call this endpoint any time your integration wants to answer one of these questions:

* Did the user already pay?
* Has provisioning started yet?
* Is the line active?
* Was the request canceled or did it fail?

This is the simplest endpoint to poll after `POST /api/line-requests`.

## Authentication

Pass your workspace API key as a Bearer token, or use a Clerk session token.

```bash theme={null}
Authorization: Bearer tuco_xxxxxxxxxxxxx
```

***

## Path parameter

<ParamField path="id" type="string">
  Required. The line request id returned by `POST /api/line-requests`.
</ParamField>

***

## Example

```bash theme={null}
curl "https://app.tuco.ai/api/line-requests/6a09279daa903300e2530b0f" \
  -H "Authorization: Bearer tuco_xxxxxxxxxxxxx"
```

### Success (`200 OK`)

```json theme={null}
{
  "success": true,
  "status": "provisioning",
  "paymentStatus": "paid",
  "paymentRequired": false,
  "line": {
    "_id": "6a09279daa903300e2530b0f",
    "firstName": "Support",
    "lastName": "Email 2",
    "channelType": "email",
    "lineType": "purchased",
    "provisioningStatus": "provisioning",
    "paymentStatus": "paid"
  }
}
```

***

## Status behavior

| `status`           | Meaning                                                                |
| ------------------ | ---------------------------------------------------------------------- |
| `awaiting_payment` | Invoice is still unpaid                                                |
| `provisioning`     | Payment is complete or not required, and Tuco is provisioning the line |
| `active`           | Line is ready to use                                                   |
| `failed`           | Provisioning did not succeed                                           |
| `canceled`         | The pending request was canceled                                       |

When possible, Tuco also reconciles a stuck `awaiting_payment` request against the latest subscription state while reading this endpoint.

### Practical meaning of each status

* `awaiting_payment`
  The request exists, but the invoice is still unpaid or billing has not been reconciled yet.
* `provisioning`
  Payment is done or was never needed, and Tuco is now setting the line up.
* `active`
  The line is ready to use in normal message flows.
* `failed`
  Provisioning did not complete. At that point the request needs review or a retry path outside this endpoint.
* `canceled`
  The pending request was intentionally canceled before completion.

### Typical polling behavior

Most clients poll after:

1. creating a paid request
2. showing the hosted invoice to the user
3. waiting for the request to move from `awaiting_payment` to `provisioning`

After that, the same endpoint can still be used until the line becomes `active`.

***

## Error responses

| Status | When                                 | Body                                     |
| ------ | ------------------------------------ | ---------------------------------------- |
| `400`  | Invalid line request id              | `{ "error": "Invalid line request id" }` |
| `401`  | Missing or invalid API key / session | `{ "error": "Unauthorized" }`            |
| `404`  | Request not found in your workspace  | `{ "error": "Line request not found" }`  |