> ## 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.

# Message Status

> A step-by-step timeline of what happened to one message — every retry, fallback and failure, in plain language.

<Note>
  Answers the question your customer actually asks: *"why didn't it arrive?"* Make
  this your tier-1 support screen.
</Note>

## Endpoint

* **Method**: `GET`
* **Path**: `/api/messages/{messageId}/journey`
* **Auth**: `Authorization: Bearer tuco_xxxxxxxxxxxxx` (workspace key)

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

## Response

Not a status string — a **timeline**. Each step records when it happened, how
serious it is, which system reported it, and copy you can show a human as-is.

```json theme={null}
{
  "steps": [
    {
      "at": 1791315902559,
      "tier": "info",
      "system": "app",
      "key": "queued",
      "label": "Send requested",
      "copy": "Message queued to send."
    },
    {
      "at": 1791315903880,
      "tier": "ok",
      "system": "imessage",
      "key": "sent",
      "label": "Sent as iMessage",
      "copy": "Delivered to your contact's iMessage."
    }
  ],
  "meta": { "source": "loki", "env": "prod", "count": 2 }
}
```

| Field | Meaning |
| - | - |
| `at` | Epoch milliseconds |
| `tier` | `ok`, `info`, `warn` or `crit` — colour it, sort by it. Note **`ok`, not `success`**, and **`crit`, not `error`** |
| `system` | Which part reported it: `app`, `device`, `imessage`, `ghl`, `hubspot` |
| `key` | Stable machine key — branch on this, not on `copy` |
| `label` / `copy` | Short title and a sentence written for an end user |

`meta` describes where the timeline was assembled from (`source`, `env`) and how
many steps it holds.

Render `copy` directly. Branch on `key`. The timeline includes retries, the
fallback ladder (iMessage → SMS → email) and the reason for any failure, so a
message that fell back shows both legs rather than just the final state.

## Error responses

| Status | When |
| - | - |
| `401` | Missing or invalid key |
| `403` | The message belongs to another workspace, or an agency key was used |
| `404` | No such message |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.