GET /api/v1/tasks
Returns the workspace's tasks, sorted by createdAt descending (newest first). Each task embeds its linked contact, lead, and deal (name + external ID) when set. Requires the read:tasks scope (or * for full access).
Request
GET /api/v1/tasks HTTP/1.1
Host: agentlyleads.com
Authorization: Bearer alk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxQuery parameters
| Parameter | Description |
|---|---|
contactExternalId | Return only tasks linked to the contact with this external ID |
leadExternalId | Return only tasks linked to the lead with this external ID |
dealExternalId | Return only tasks linked to the deal with this external ID |
done | true or false |
type | TODO, CALL, EMAIL, or MEETING |
updatedSince | ISO 8601 datetime — only tasks updated at or after this moment |
limit | Page size, 1–1000 (default 100) |
cursor | The nextCursor value from the previous page |
All parameters are optional and can be combined. Filters that match nothing return an empty list, not a 404.
Upcoming appointments for one contact:
GET /api/v1/tasks?contactExternalId=hs_contact_123&type=MEETING&done=false HTTP/1.1
Authorization: Bearer alk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxResponse — 200
{
"tasks": [
{
"id": "cmq7task0alk34567890",
"title": "Discovery call with Acme",
"done": false,
"dueDate": "2026-09-10T14:00:00.000Z",
"allDay": false,
"endAt": "2026-09-10T14:30:00.000Z",
"description": null,
"type": "MEETING",
"priority": "MEDIUM",
"externalId": "booking_9F3K2",
"contact": { "name": "Jane Buyer", "externalId": "hs_contact_123" },
"lead": null,
"deal": null,
"createdAt": "2026-08-01T09:12:00.000Z",
"updatedAt": "2026-08-01T09:12:00.000Z"
}
],
"nextCursor": null
}contact, lead, and deal are null when the task has no such link. dueDate/endAt are always returned as full ISO 8601 datetimes, regardless of the shape they were written in.
Pagination
Responses are cursor-paginated. When more rows exist beyond the requested limit, nextCursor holds the ID of the last returned record — pass it back as cursor to fetch the next page. On the last page, nextCursor is null.