> ## Documentation Index
> Fetch the complete documentation index at: https://developer.lemlist.com/llms.txt
> Use this file to discover all available pages before exploring further.
> Searches your team's tasks with the filters of the Tasks page, and returns every status.
# Search Tasks
This is the v2 of [Get Many Tasks](/api-reference/endpoints/tasks/get-many-tasks). It
addresses the same search engine as the Tasks page in the app, so anything you can
filter on there, you can filter on here.
Two tiers of filtering:
* **Flat query parameters** for the common cases — `status=due&assignedTo=usr_...`
* **`advancedFilters`**, a JSON tree, for everything else, including your custom
fields. [List the available fields](/api-reference/endpoints/tasks/get-task-filters)
to discover them.
Unlike v1, completed tasks are returned. v1 only ever served `due`, `upcoming`
and `paused` tasks; v2 returns every status unless `status` narrows it.
## Filtering
Any list parameter takes a single value, a comma-separated list, or the repeated
`key[]=` notation — the three are equivalent. Values are OR-ed inside a parameter,
AND-ed across parameters. `taskId`, `contactId`, `companyId`, `leadId`,
`campaignId`, `assignedTo` and `type` each take a `…Not` counterpart for exclusion.
| Parameter | Narrows to |
| ------------------------------------ | --------------------------------------------------------- |
| `taskId` | These task ids (100 max) |
| `objectType` | Contact tasks, or company tasks |
| `contactId` | The contact's tasks, its leads' tasks included |
| `companyId` | The company's tasks, and the tasks of its contacts |
| `leadId`, `campaignId`, `assignedTo` | The given ids |
| `type`, `channel` | The step type, or the coarser channel |
| `status`, `priority` | Task status and priority |
| `title`, `contactLinkedinUrl` | Substring match |
| `dueDateFrom` / `dueDateTo` | Due-date range, inclusive, ISO-8601 |
| `completedAtFrom` / `completedAtTo` | Completion-date range (done or ignored) |
| `hasCampaign`, `hasDueDate` | Presence of a campaign, of a due date |
| `search` | Free text over the title and the contact / company fields |
| `advancedFilters` | Anything else — see below |
### Statuses
`due`, `upcoming`, `paused`, `done`, `ignored`. `pending` is an alias for
`due,upcoming,paused`.
`upcoming` is maintained by a background job, not computed when you read: a task
crossing its due date flips to `due` on the next sweep, not at the exact instant.
Filter on `dueDate` when you need a read-time-exact answer.
## Advanced filters
`advancedFilters` takes a filter tree encoded as JSON. A node is either a
**group** (`connector` `and` / `or`, plus `children`) or a **condition**
(`property`, `operator`, `value`). The tree is bounded: **depth 5, 50 conditions**.
```json theme={"theme":"dracula"}
{
"type": "group",
"id": "root",
"connector": "and",
"children": [
{
"type": "condition",
"id": "c1",
"property": "contactLeadStatus",
"operator": "is_any_of",
"value": ["Email sent"]
},
{
"type": "group",
"id": "g1",
"connector": "or",
"children": [
{
"type": "condition",
"id": "c2",
"property": "companyIndustry",
"operator": "contains",
"value": "software"
},
{
"type": "condition",
"id": "c3",
"property": "cf_contact_tier",
"operator": "is",
"value": "A"
}
]
}
]
}
```
Every `property` must be a field returned by
[List Task Filters](/api-reference/endpoints/tasks/get-task-filters), and every
`operator` must be one that field's type allows. An unknown field or a wrong
operator is a `400` — never a silently ignored condition.
## Sorting and pagination
`sortBy` accepts `dueDate` (default), `status`, `priority`, `assignedTo`,
`campaignId`, `score`, `handledOn` and `contactJobTitle`; `sortOrder` is `asc` or
`desc` (default `desc`).
Pagination is offset-based and **1-based**: `page` (default 1) and `limit`
(default 50, max 100). `page * limit` must not exceed **10 000** — past that the
request returns `400 PAGE_OUT_OF_RANGE` rather than silently serving another page.
## Coming from v1
| v1 filter | v2 | Note |
| --------------- | ----------------------------------- | ---------------------------------------------------------- |
| `fullName` | `advancedFilters` on `contactName` | |
| `email` | `advancedFilters` on `contactEmail` | |
| `phone` | `advancedFilters` on `contactPhone` | |
| `campaignId` | `campaignId` / `campaignIdNot` | |
| `assignedTo` | `assignedTo` / `assignedToNot` | User ids, same values |
| `type` | `type` / `typeNot` | Same raw vocabulary |
| `dueDate` | `dueDateFrom` / `dueDateTo` | ISO-8601 instead of `YYYY-MM-DD` |
| `linkedin` | `contactLinkedinUrl` | Matches the **contact's** URL, where v1 matched the lead's |
| `campaignState` | — | No equivalent, see below |
Also worth knowing when porting a query:
* `page` is 1-based here, where v1 is 0-indexed.
* The response is `{ results, total, limit, page }`, and every task key is always
present — `null` rather than omitted.
* Dates are ISO-8601 instants.
## Limits
* **No `createdAt` / `updatedAt`.** A task's real creation timestamp only exists on
part of the data, and no update timestamp is indexed — so neither can be filtered
nor sorted on. `dueDate` and `completedAt` are the reliable ones.
* **No `campaignState`.** v1 could filter tasks by the state of their campaign; the
task document does not carry it. Fetch the campaigns and filter on your side.
* **No cursor pagination.** Offset only, capped at 10 000 rows: narrow with a date
range to walk a larger set.
* **`source` is not available.** The nearest signals are `manual` in the response
and the `hasCampaign` parameter.
## Examples
```bash Due tasks of one user theme={"theme":"dracula"}
curl --request GET \
--url 'https://api.lemlist.com/api/v2/tasks?status=due&assignedTo=usr_A1B2C3D4E5F6G7H8I&limit=50' \
--header 'Authorization: Basic '
```
```bash Every task of a company, its contacts included theme={"theme":"dracula"}
curl --request GET \
--url 'https://api.lemlist.com/api/v2/tasks?companyId=cmp_A1B2C3D4E5F6G7H8I&sortBy=dueDate&sortOrder=asc' \
--header 'Authorization: Basic '
```
```bash Tasks completed in January theme={"theme":"dracula"}
curl --request GET \
--url 'https://api.lemlist.com/api/v2/tasks?status=done&completedAtFrom=2026-01-01T00:00:00.000Z&completedAtTo=2026-01-31T23:59:59.999Z' \
--header 'Authorization: Basic '
```
```bash Advanced filter, with the contact embedded theme={"theme":"dracula"}
curl --request GET \
--url 'https://api.lemlist.com/api/v2/tasks?include=contact' \
--data-urlencode 'advancedFilters={"type":"condition","id":"c1","property":"contactLeadStatus","operator":"is_any_of","value":["Email sent"]}' \
--get \
--header 'Authorization: Basic '
```
## OpenAPI
````yaml get /v2/tasks
openapi: 3.0.0
info:
title: lemlist API
version: 1.0.0
description: >-
Welcome to the lemlist Developer Documentation.
lemlist is very customizable and open. You'll find on this page all the API
and integration you can do with lemlist.
# Rate Limit
lemlist's API rate limits requests in order to prevent abuse and overload of
our services.
Rate limits are applied on all routes and per API key performing the
request.
The rate limits are **20** requests per **2** seconds.
The response provides any information you may need about it:
| Header | Description |
| --- | --- |
| Retry-After | The number of seconds in which you can retry |
| X-RateLimit-Limit | The maximum requests in that time |
| X-RateLimit-Remaining | The number of remaining requests you can make |
| X-RateLimit-Reset | The date when the rate limit will reset |
_Example of values for the rate limit headers_
``` json
{
"Retry-After": 2,
"X-RateLimit-Limit": 20,
"X-RateLimit-Remaining": 7,
"X-RateLimit-Reset" : "Tue Feb 16 2021 09:02:42 GMT+0100 (Central European Standard Time)"
}
```
# Definitions
## Team
A team is the entity of lemlist that can handle users and billing.
## Credits
Credits are the coins a team uses to enrich emails, LinkedIn URLs, etc. via
the enrich route. Each enrichment feature needs a certain amount of credits
to run.
## User
You use a user account to connect to lemlist and send messages via the
connected emails or LinkedIn account.
## Campaign
A campaign is the entity to automate outreach. A campaign has multiple
sequences composed of steps.
## Lead
A lead is a person that you try to contact via a campaign.
## Activity
An activity is the history of all the steps.
## Unsubscribe
An unsubscribe occurs when a person decides they don't want to receive
emails from you anymore.
# Authentication
All API routes use the dedicated subdomain `api.lemlist.com`.
lemlist uses API keys to allow access to the API. You can get your lemlist
API key at our [integration
page](https://app.lemlist.com/settings/integrations).
You need to add the `Authorization` header using the `Basic` authentication
type. `login:password` **where the login is always empty and the password is
the API key**.
⚠️ **Don't forget to add the semicolon (**`:`**) before your API key in curl
command.**
> To authorize, use this code:
``` shell
curl https://api.lemlist.com/api/team \
--user ":YourApiKey"
```
**Make sure to replace** **`YourApiKey`** **with your API key.**
# Give feedback
If you want to report a bug, ask for data, or share with us a use case,
please fill this [form](https://lemlist.typeform.com/to/mfVlkyGf). It will
help us centralize your needs!
servers:
- url: https://api.lemlist.com/api
security:
- basicAuth: []
paths:
/v2/tasks:
get:
tags:
- Tasks
summary: Search Tasks
description: >-
Searches the team's tasks with the same vocabulary as the Tasks page:
flat query parameters for the common filters, and an `advancedFilters`
tree for everything else. Every status is returned unless `status`
narrows it.
parameters:
- name: taskId
in: query
required: false
description: >-
Task ids. At most 100. Several values (comma-separated or repeated)
are OR-ed.
schema:
type: string
example: opp_A1B2C3D4E5F6G7H8I
- name: contactId
in: query
required: false
description: >-
Contact ids. A single id also matches the tasks of that contact's
leads, exactly like the contact panel does. Several values
(comma-separated or repeated) are OR-ed.
schema:
type: string
example: ctc_A1B2C3D4E5F6G7H8I
- name: contactIdNot
in: query
required: false
description: Excludes the given `contactId` values.
schema:
type: string
example: ctc_A1B2C3D4E5F6G7H8I
- name: companyId
in: query
required: false
description: >-
Company ids. Matches company-level tasks AND tasks on that company's
contacts. Several values (comma-separated or repeated) are OR-ed.
schema:
type: string
example: cmp_A1B2C3D4E5F6G7H8I
- name: companyIdNot
in: query
required: false
description: Excludes the given `companyId` values.
schema:
type: string
example: cmp_A1B2C3D4E5F6G7H8I
- name: leadId
in: query
required: false
description: Lead ids. Several values (comma-separated or repeated) are OR-ed.
schema:
type: string
example: lea_A1B2C3D4E5F6G7H8I
- name: leadIdNot
in: query
required: false
description: Excludes the given `leadId` values.
schema:
type: string
example: lea_A1B2C3D4E5F6G7H8I
- name: campaignId
in: query
required: false
description: >-
Campaign ids. Several values (comma-separated or repeated) are
OR-ed.
schema:
type: string
example: cam_A1B2C3D4E5F6G7H8I
- name: campaignIdNot
in: query
required: false
description: Excludes the given `campaignId` values.
schema:
type: string
example: cam_A1B2C3D4E5F6G7H8I
- name: assignedTo
in: query
required: false
description: >-
Ids of the users the task is assigned to. Several values
(comma-separated or repeated) are OR-ed.
schema:
type: string
example: usr_A1B2C3D4E5F6G7H8I
- name: assignedToNot
in: query
required: false
description: Excludes the given `assignedTo` values.
schema:
type: string
example: usr_A1B2C3D4E5F6G7H8I
- name: objectType
in: query
required: false
description: >-
Restricts to the tasks hanging off a contact (a `contactId` or a
`leadId` is present) or off a company (a `companyId` with no contact
and no lead). Derived from the ids, never stored.
schema:
type: string
enum:
- contact
- company
example: company
- name: type
in: query
required: false
description: >-
Raw step types, comma-separated. This is the same vocabulary as v1
`type`.
schema:
type: string
example: phone,linkedinSend
- name: typeNot
in: query
required: false
description: Excludes the given `type` values.
schema:
type: string
- name: channel
in: query
required: false
description: >-
Channel the task belongs to — the coarser nomenclature shown in the
app as "Task type".
schema:
type: string
enum:
- aircall
- email
- linkedin
- whatsapp
- sms
- manual
example: linkedin
- name: status
in: query
required: false
description: >-
Task statuses, comma-separated. `pending` is an alias for
`due,upcoming,paused`. Unlike v1, completed tasks are returned
unless you filter them out.
schema:
type: string
enum:
- due
- upcoming
- paused
- done
- ignored
- pending
example: pending
- name: priority
in: query
required: false
description: Task priorities (integers), comma-separated.
schema:
type: string
example: 1,2
- name: title
in: query
required: false
description: Matches tasks whose title contains this text.
schema:
type: string
- name: contactLinkedinUrl
in: query
required: false
description: >-
Matches tasks whose contact's LinkedIn URL contains this text. v1's
`linkedin` filter matched the lead's URL instead.
schema:
type: string
example: linkedin.com/in/johndoe
- name: dueDateFrom
in: query
required: false
description: Lower bound of the due date, inclusive. ISO-8601.
schema:
type: string
format: date-time
example: '2026-01-01T00:00:00.000Z'
- name: dueDateTo
in: query
required: false
description: Upper bound of the due date, inclusive. ISO-8601.
schema:
type: string
format: date-time
example: '2026-01-31T23:59:59.999Z'
- name: completedAtFrom
in: query
required: false
description: >-
Lower bound of the completion date (done or ignored), inclusive.
ISO-8601.
schema:
type: string
format: date-time
- name: completedAtTo
in: query
required: false
description: >-
Upper bound of the completion date (done or ignored), inclusive.
ISO-8601.
schema:
type: string
format: date-time
- name: hasCampaign
in: query
required: false
description: >-
Restricts to the tasks attached to a campaign (`true`) or to the
standalone ones (`false`).
schema:
type: boolean
- name: hasDueDate
in: query
required: false
description: >-
Restricts to the tasks carrying a due date (`true`) or to those
without one (`false`).
schema:
type: boolean
- name: search
in: query
required: false
description: >-
Free-text search over the task title and the contact / company text
fields.
schema:
type: string
- name: advancedFilters
in: query
required: false
description: >-
A filter tree encoded as JSON, addressing any field returned by `GET
/v2/tasks/filters`. Max depth 5, max 50 conditions.
schema:
type: string
example: >-
{"type":"group","id":"root","connector":"and","children":[{"type":"condition","id":"c1","property":"contactLeadStatus","operator":"is_any_of","value":["Email
sent"]}]}
- name: include
in: query
required: false
description: >-
Embeds the denormalized objects already carried by the task.
Comma-separated.
schema:
type: string
enum:
- contact
- company
- contact,company
example: contact
- name: sortBy
in: query
required: false
description: Field to sort on.
schema:
type: string
enum:
- dueDate
- status
- priority
- assignedTo
- campaignId
- score
- handledOn
- contactJobTitle
default: dueDate
- name: sortOrder
in: query
required: false
description: Sort direction.
schema:
type: string
enum:
- asc
- desc
default: desc
- name: page
in: query
required: false
description: Page number, 1-based. `page * limit` must not exceed 10000.
schema:
type: integer
minimum: 1
default: 1
- name: limit
in: query
required: false
description: Page size.
schema:
type: integer
minimum: 1
maximum: 100
default: 50
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/TaskV2ListResponse'
example:
results:
- _id: opp_A1B2C3D4E5F6G7H8I
objectType: contact
recordId: ctc_A1B2C3D4E5F6G7H8I
contactId: ctc_A1B2C3D4E5F6G7H8I
companyId: cmp_A1B2C3D4E5F6G7H8I
leadId: lea_A1B2C3D4E5F6G7H8I
campaignId: cam_A1B2C3D4E5F6G7H8I
assignedTo: usr_A1B2C3D4E5F6G7H8I
title: Call John Doe
message: Ask about the new pricing
text: null
type: phone
channel: aircall
status: due
priority: 2
dueDate: '2026-01-12T09:00:00.000Z'
completedAt: null
manual: true
ownerName: Jane Smith
campaign:
id: cam_A1B2C3D4E5F6G7H8I
name: Q1 outbound
sequenceId: seq_A1B2C3D4E5F6G7H8I
leadFirstName: John
leadLastName: Doe
leadCompanyName: Acme Inc
total: 1
limit: 50
page: 1
'400':
description: >-
Invalid parameter — an unknown field, an operator the field type
does not allow, an unknown `sortBy`, a malformed date range, a
filter tree over the allowed bounds, or a page beyond the maximum
result window.
content:
application/json:
schema:
$ref: '#/components/schemas/TaskV2Error'
example:
success: false
error:
code: UNKNOWN_FIELD
message: 'Unknown filter field: contactFoo'
'401':
description: The authentication you supplied is incorrect.
content:
application/json:
schema:
$ref: '#/components/schemas/TaskV2Error'
example:
success: false
error:
code: ROUTE_UNAUTHORIZED
message: Unauthorized
'405':
description: Method not allowed — these routes are read-only.
content:
application/json:
schema:
type: object
properties:
error:
type: string
example:
error: Method not allowed
'500':
description: The search failed.
content:
application/json:
schema:
$ref: '#/components/schemas/TaskV2Error'
example:
success: false
error:
code: SEARCH_FAILED
message: Failed to search tasks
components:
schemas:
TaskV2ListResponse:
type: object
description: Paginated response of `GET /v2/tasks`.
properties:
results:
type: array
items:
$ref: '#/components/schemas/TaskV2'
total:
type: integer
description: Total number of matching tasks
limit:
type: integer
description: Page size used
page:
type: integer
description: Page returned, 1-based
TaskV2Error:
type: object
description: Error envelope of the v2 task routes.
properties:
success:
type: boolean
example: false
error:
type: object
properties:
code:
type: string
description: Machine-readable error code
enum:
- INVALID_PARAMETER
- UNKNOWN_FIELD
- FIELD_TYPE_MISMATCH
- INVALID_ADVANCED_FILTERS
- FILTER_TREE_TOO_COMPLEX
- UNKNOWN_SORT_FIELD
- INVALID_DATE_RANGE
- PAGE_OUT_OF_RANGE
- SEARCH_FAILED
- ROUTE_UNAUTHORIZED
- ROUTE_BAD_METHOD
message:
type: string
description: What was wrong, and what is allowed
TaskV2:
type: object
description: >-
A task as returned by `GET /v2/tasks`. Every key is always present —
`null` rather than omitted.
properties:
_id:
type: string
description: Unique task identifier
objectType:
type: string
nullable: true
enum:
- contact
- company
description: Which record the task hangs off, derived from the ids
recordId:
type: string
nullable: true
description: >-
Id of that record — the company id for a company task, the contact
id (or the lead id) otherwise
contactId:
type: string
nullable: true
description: Associated contact id
companyId:
type: string
nullable: true
description: Company id of the task, or of its contact
leadId:
type: string
nullable: true
description: Associated lead id
campaignId:
type: string
nullable: true
description: Campaign id
assignedTo:
type: string
nullable: true
description: Id of the user the task is assigned to
title:
type: string
nullable: true
description: Task title
message:
type: string
nullable: true
description: Body of the task
text:
type: string
nullable: true
description: >-
Body of the reply that opened the task — `opportunityReplied` tasks
only
type:
type: string
nullable: true
description: Raw step type
enum:
- manual
- phone
- email
- linkedinInvite
- linkedinSend
- linkedinVoiceNote
- whatsappMessage
- opportunityReplied
- opportunityClicked
channel:
type: string
nullable: true
description: Channel of the task
enum:
- aircall
- email
- linkedin
- whatsapp
- sms
- manual
status:
type: string
nullable: true
description: Task status
enum:
- due
- upcoming
- paused
- done
- ignored
priority:
type: integer
nullable: true
description: Task priority
dueDate:
type: string
format: date-time
nullable: true
description: Due date
completedAt:
type: string
format: date-time
nullable: true
description: Date the task was done or ignored
manual:
type: boolean
description: True when the task comes from a manual campaign step
ownerName:
type: string
nullable: true
description: Full name of the assigned user
campaign:
type: object
nullable: true
description: Campaign the task belongs to
properties:
id:
type: string
name:
type: string
sequenceId:
type: string
nullable: true
leadFirstName:
type: string
nullable: true
description: Lead's first name
leadLastName:
type: string
nullable: true
description: Lead's last name
leadCompanyName:
type: string
nullable: true
description: Lead's company name
contact:
type: object
nullable: true
description: Denormalized contact — only with `include=contact`
company:
type: object
nullable: true
description: Denormalized company — only with `include=company`
securitySchemes:
basicAuth:
type: http
scheme: basic
````