# List scheduled callbacks (/api-reference/campaigns/listCallbacks)

## GET /api/v1/callbacks

Operation ID: `listCallbacks`
List scheduled callbacks
Callbacks your agents booked during calls and reminder calls from your rules, soonest first. Use `leadId` to see what is booked for one lead.

### Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `status` | query | no | Comma-separated statuses, or `all`. Default `pending,queued,dialing` (still to happen). |
| `kind` | query | no | `callback` or `reminder`. |
| `leadId` | query | no | Only this lead's callbacks. |
| `campaignId` | query | no | Only this campaign's callbacks. |
| `agentId` | query | no | Only this agent's callbacks. |
| `dateFrom` | query | no | `dialAt` at or after this ISO 8601 time. |
| `dateTo` | query | no | `dialAt` at or before this ISO 8601 time. |
| `limit` | query | no | Page size, 1 to 200. |
| `offset` | query | no | Callbacks to skip. |

### Responses

#### 200 OK

Schema:

```json
{
  "additionalProperties": true,
  "description": "One page of callbacks, soonest first.",
  "properties": {
    "callbacks": {
      "description": "Callbacks on this page, by `dialAt`.",
      "items": {
        "additionalProperties": true,
        "description": "A callback or reminder call booked for a lead.",
        "properties": {
          "agentId": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Agent that places the call.",
            "title": "Agentid"
          },
          "attempts": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "description": "Calls placed for this booking so far.",
            "title": "Attempts"
          },
          "callId": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Latest call placed for this booking.",
            "title": "Callid"
          },
          "campaignId": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Campaign whose agent and caller ID place the call.",
            "title": "Campaignid"
          },
          "campaignName": {
            "default": "",
            "description": "Campaign's name.",
            "title": "Campaignname",
            "type": "string"
          },
          "channel": {
            "default": "phone",
            "description": "How the lead is reached, usually `phone`.",
            "title": "Channel",
            "type": "string"
          },
          "createdAt": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "When it was booked (ISO 8601).",
            "title": "Createdat"
          },
          "dialAt": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Time the call will be placed; later than `dueAt` when moved into the dial window.",
            "title": "Dialat"
          },
          "dialAtLocal": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "`dialAt` in `timezone`, for display.",
            "title": "Dialatlocal"
          },
          "dueAt": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Time the lead asked for (ISO 8601, UTC).",
            "title": "Dueat"
          },
          "id": {
            "description": "Callback ID.",
            "title": "Id",
            "type": "string"
          },
          "kind": {
            "description": "`callback` (the lead asked to be called) or `reminder` (from a reminder rule).",
            "title": "Kind",
            "type": "string"
          },
          "lastOutcome": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Outcome of the latest attempt.",
            "title": "Lastoutcome"
          },
          "leadId": {
            "description": "Lead to call back.",
            "title": "Leadid",
            "type": "string"
          },
          "leadName": {
            "default": "",
            "description": "Lead's name.",
            "title": "Leadname",
            "type": "string"
          },
          "leadPhone": {
            "default": "",
            "description": "Lead's phone number.",
            "title": "Leadphone",
            "type": "string"
          },
          "maxAttempts": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "description": "Calls allowed before it is marked `failed`.",
            "title": "Maxattempts"
          },
          "note": {
            "default": "",
            "description": "Note shown to the agent on the call.",
            "title": "Note",
            "type": "string"
          },
          "originCallId": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Call during which the callback was booked.",
            "title": "Origincallid"
          },
          "purpose": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Why the call is booked.",
            "title": "Purpose"
          },
          "shifted": {
            "default": false,
            "description": "True when `dialAt` was moved into the dial window.",
            "title": "Shifted",
            "type": "boolean"
          },
          "source": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "What booked it: the agent during a call, a person, or a rule.",
            "title": "Source"
          },
          "status": {
            "description": "`pending`, `queued`, `dialing`, `done`, `failed`, `cancelled` or `expired`.",
            "title": "Status",
            "type": "string"
          },
          "timezone": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "IANA time zone used for the booking.",
            "title": "Timezone"
          }
        },
        "required": [
          "id",
          "leadId",
          "kind",
          "status"
        ],
        "title": "ScheduledCallbackItem",
        "type": "object"
      },
      "title": "Callbacks",
      "type": "array"
    },
    "total": {
      "description": "Callbacks matching the filters.",
      "title": "Total",
      "type": "integer"
    }
  },
  "required": [
    "callbacks",
    "total"
  ],
  "title": "ScheduledCallbackList",
  "type": "object"
}
```

#### 400 Bad request: `workspace_required`.

Example (Merchant workspace required):

```json
{
  "detail": "Merchant workspace required",
  "error": {
    "code": "workspace_required",
    "docUrl": "https://docs.callmitra.ai/errors/workspace_required",
    "message": "Merchant workspace required",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "invalid_request_error"
  }
}
```

#### 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"
  }
}
```

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

- [`workspace_required`](/errors/workspace_required)
- [`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)
- [`parameter_invalid`](/errors/parameter_invalid)
- [`rate_limit_exceeded`](/errors/rate_limit_exceeded)
- [`internal_error`](/errors/internal_error)
