# Lead timeline (/api-reference/leads/getLeadTimeline)

## GET /api/v1/leads/{lead_id}/timeline

Operation ID: `getLeadTimeline`
Lead timeline
Calls, WhatsApp messages and orders, tickets, notes, lead changes and callbacks for one lead, newest first. Page with `cursor`; the first page also lists open callbacks.

### Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `lead_id` | path | yes | Lead ID. |
| `cursor` | query | no | `nextCursor` from the previous page. |
| `limit` | query | no | Items per page, 1 to 100 (default 30). |
| `types` | query | no | Comma list of `call`, `whatsapp`, `ticket`, `note`, `change`, `callback`. |

### Responses

#### 200 OK

Schema:

```json
{
  "additionalProperties": true,
  "description": "One page of a lead's timeline, newest first.",
  "properties": {
    "hasMore": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "description": "True when another page follows.",
      "title": "Hasmore"
    },
    "items": {
      "description": "Events on this page.",
      "items": {
        "additionalProperties": true,
        "description": "One event on a lead's timeline.",
        "properties": {
          "at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "When it happened.",
            "format": "date-time",
            "title": "At"
          },
          "body": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Detail text: call summary, message text, note body.",
            "title": "Body"
          },
          "href": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Path of the matching console page, when there is one.",
            "title": "Href"
          },
          "id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "ID of the call, message, note or other source row.",
            "title": "Id"
          },
          "meta": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "description": "Source-specific fields, such as call status.",
            "title": "Meta"
          },
          "title": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "One-line summary, for example `Outbound call · 2m 05s`.",
            "title": "Title"
          },
          "type": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Source: `call`, `whatsapp`, `order`, `ticket`, `note`, `change` or `callback`.",
            "title": "Type"
          }
        },
        "title": "TimelineItem",
        "type": "object"
      },
      "title": "Items",
      "type": "array"
    },
    "nextCursor": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Pass as `cursor` for the next page; null on the last.",
      "title": "Nextcursor"
    },
    "success": {
      "default": true,
      "description": "Always true on a 2xx response.",
      "title": "Success",
      "type": "boolean"
    },
    "upcomingCallbacks": {
      "anyOf": [
        {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "description": "First page only: open callbacks and reminders, soonest first (callbackId, kind, channel, status, dueAt, dialAt, purpose, note, overdue).",
      "title": "Upcomingcallbacks"
    }
  },
  "required": [
    "items"
  ],
  "title": "LeadTimeline",
  "type": "object"
}
```

#### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`.

Example (The API key has expired.):

```json
{
  "detail": "The API key has expired.",
  "error": {
    "code": "api_key_expired",
    "docUrl": "https://docs.callmitra.ai/errors/api_key_expired",
    "message": "The API key has expired.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "authentication_error"
  }
}
```

Example (The API key is invalid or has been revoked.):

```json
{
  "detail": "The API key is invalid or has been revoked.",
  "error": {
    "code": "invalid_api_key",
    "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key",
    "message": "The API key is invalid or has been revoked.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "authentication_error"
  }
}
```

Example (Authentication required.):

```json
{
  "detail": "Authentication required.",
  "error": {
    "code": "unauthenticated",
    "docUrl": "https://docs.callmitra.ai/errors/unauthenticated",
    "message": "Authentication required.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "authentication_error"
  }
}
```

#### 403 Forbidden: `api_key_scope_denied`, `permission_denied`.

Example (The API key does not have the scope required for this request.):

```json
{
  "detail": "The API key does not have the scope required for this request.",
  "error": {
    "code": "api_key_scope_denied",
    "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied",
    "message": "The API key does not have the scope required for this request.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "permission_error"
  }
}
```

Example (You do not have permission to perform this action.):

```json
{
  "detail": "You do not have permission to perform this action.",
  "error": {
    "code": "permission_denied",
    "docUrl": "https://docs.callmitra.ai/errors/permission_denied",
    "message": "You do not have permission to perform this action.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "permission_error"
  }
}
```

#### 404 Not found: `lead_not_found`.

Example (Lead not found.):

```json
{
  "detail": "Lead not found.",
  "error": {
    "code": "lead_not_found",
    "docUrl": "https://docs.callmitra.ai/errors/lead_not_found",
    "message": "Lead not found.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "not_found_error"
  }
}
```

#### 422 Invalid parameters: `parameter_invalid`.

Example (One or more parameters are invalid.):

```json
{
  "detail": [
    {
      "loc": [
        "body",
        "phone"
      ],
      "msg": "Field required",
      "type": "missing"
    }
  ],
  "error": {
    "code": "parameter_invalid",
    "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid",
    "message": "One or more parameters are invalid.",
    "param": "phone",
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "invalid_request_error"
  }
}
```

#### 429 Too many requests: `rate_limit_exceeded`.

Example (Too many requests. Slow down and retry later.):

```json
{
  "detail": "Too many requests. Slow down and retry later.",
  "error": {
    "code": "rate_limit_exceeded",
    "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded",
    "message": "Too many requests. Slow down and retry later.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "rate_limit_error"
  }
}
```

#### 500 Server error: `internal_error`.

Example (Something went wrong on our side.):

```json
{
  "detail": "Something went wrong on our side.",
  "error": {
    "code": "internal_error",
    "docUrl": "https://docs.callmitra.ai/errors/internal_error",
    "message": "Something went wrong on our side.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "api_error"
  }
}
```

### Error codes

- [`api_key_expired`](/errors/api_key_expired)
- [`invalid_api_key`](/errors/invalid_api_key)
- [`unauthenticated`](/errors/unauthenticated)
- [`api_key_scope_denied`](/errors/api_key_scope_denied)
- [`permission_denied`](/errors/permission_denied)
- [`lead_not_found`](/errors/lead_not_found)
- [`parameter_invalid`](/errors/parameter_invalid)
- [`rate_limit_exceeded`](/errors/rate_limit_exceeded)
- [`internal_error`](/errors/internal_error)
