> ## 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.
> Retrieves paginated signals detected by your Signal Agents with filtering and sorting capabilities.
# Get Signal Agent signals
export const SnippetObjectReference = ({objectName, objectPath = null}) => {
const lowerCaseObjectName = objectName.toLowerCase();
if (lowerCaseObjectName === 'lead' || lowerCaseObjectName === 'leads') {
return
This endpoint uses the {objectName} object. Make sure to also check the {lowerCaseObjectName === 'lead' ? 'Contact' : 'Lead'} object to understand the distinction between the two.
;
}
return
This endpoint uses the {objectName} object.
;
};
This endpoint allows you to fetch signals detected by your Signal Agents with support for filtering by type, status, date range, and Signal Agent ID.
## OpenAPI
````yaml get /watchlist/signals
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:
/watchlist/signals:
get:
tags:
- Signal Agents
summary: Get Signal Agent signals
parameters:
- name: page
in: query
required: false
description: Page number to retrieve (cannot be used with offset)
example: '1'
schema:
type: integer
minimum: 1
- name: offset
in: query
required: false
description: Number of records to skip (cannot be used with page)
example: '0'
schema:
type: integer
minimum: 0
- name: limit
in: query
required: false
description: 'Number of signals to retrieve. Maximum value: 100'
example: '50'
schema:
type: integer
minimum: 1
maximum: 100
- name: sortBy
in: query
required: false
description: The field by which to sort signals
example: receivedAt
schema:
type: string
enum:
- receivedAt
- createdAt
- name: sortOrder
in: query
required: false
description: The sort direction
example: desc
schema:
type: string
enum:
- asc
- desc
- name: type
in: query
required: false
description: >-
Filter by signal type(s). Can be a single value or array using
type[] notation. Valid values from
WATCH_LIST_SIGNAL_CONFIGURATIONS_TYPES_STANDARD_KEYS
example: jobChange
schema:
oneOf:
- type: string
- type: array
items:
type: string
- name: status
in: query
required: false
description: >-
Filter by signal status(es). Can be a single value or array using
status[] notation. Valid values from
WATCH_LIST_SIGNAL_COMPUTED_STATUSES
example: new
schema:
oneOf:
- type: string
- type: array
items:
type: string
- name: receivedAtFrom
in: query
required: false
description: Filter signals received on or after this date (ISO date string)
example: '2024-01-01T00:00:00.000Z'
schema:
type: string
format: date-time
- name: receivedAtTo
in: query
required: false
description: >-
Filter signals received on or before this date (ISO date string).
Must be greater than receivedAtFrom if both are provided
example: '2024-12-31T23:59:59.999Z'
schema:
type: string
format: date-time
- name: watchListId
in: query
required: false
description: Filter signals by specific Signal Agent ID
example: wl_abc123
schema:
type: string
minLength: 1
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/WatchListApiFetchSignalsResponse'
'400':
description: >-
Validation error - invalid query parameters, pagination conflict, or
invalid date range
content:
text/plain:
examples:
invalidPagination:
value: page must be a positive integer
paginationConflict:
value: Cannot use both page and offset parameters
invalidLimit:
value: limit must be between 1 and 100
invalidSort:
value: sortBy must be either receivedAt or createdAt
invalidType:
value: 'Invalid type values: invalid_type'
invalidStatus:
value: 'Invalid status values: invalid_status'
invalidDate:
value: receivedAtFrom must be a valid ISO date string
invalidDateRange:
value: receivedAtFrom must be before receivedAtTo
'401':
description: Unauthorized - invalid or missing API key
content:
text/plain:
example: Unauthorized
'404':
description: Watchlist not found
content:
text/plain:
example: Watchlist not found
'405':
description: Method not allowed - only GET is supported
content:
text/plain:
example: Method not allowed
'500':
description: Internal server error
content:
text/plain:
example: Internal server error
security:
- ApiKeyAuth: []
components:
schemas:
WatchListApiFetchSignalsResponse:
type: object
description: Paginated response containing signals detected by Signal Agents
properties:
signals:
type: array
description: Array of signals matching the query parameters
items:
$ref: '#/components/schemas/SignalSchema'
total:
type: integer
description: Total number of signals matching the filter criteria
page:
type: integer
description: Current page number (if using page-based pagination)
offset:
type: integer
description: Current offset (if using offset-based pagination)
limit:
type: integer
description: Number of signals returned in this response
SignalSchema:
type: object
description: >-
A signal detected by a Signal Agent representing a tracked event
(hiring, LinkedIn activity, website visit, etc.)
required:
- _id
- teamId
- watchListId
- type
- status
- receivedAt
- createdAt
- signalData
properties:
_id:
type: string
description: Unique signal identifier
teamId:
type: string
description: Team ID that owns this signal
watchListId:
type: string
description: ID of the Signal Agent associated with this signal
watchListName:
type: string
description: Name of the Signal Agent associated with this signal
type:
type: string
description: Signal type
enum:
- companyIsHiring
- companyRaisedFunds
- jobChange
- newHire
- companyEmployeeVisitedMyWebsite
- linkedinProfile
- linkedinTopic
status:
type: string
description: Signal status (computed based on user actions)
enum:
- new
- old
- handled
- ignored
receivedAt:
type: string
format: date-time
description: When the signal was received
createdAt:
type: string
format: date-time
description: When the signal was created in the database
contact:
type: object
description: Contact associated with this signal (if entity type is 'contact')
properties:
_id:
type: string
description: Contact ID
firstName:
type: string
description: Contact first name
lastName:
type: string
description: Contact last name
email:
type: string
description: Contact primary email
jobTitle:
type: string
description: Contact job title
phone:
type: string
description: Contact phone number
linkedinUrl:
type: string
description: Contact LinkedIn profile URL
picture:
type: string
description: Contact profile picture URL
company:
type: object
description: Company associated with this signal
properties:
_id:
type: string
description: Company ID
name:
type: string
description: Company name
domain:
type: string
description: Company website domain
linkedinUrl:
type: string
description: Company LinkedIn URL
industry:
type: string
description: Company industry
picture:
type: string
description: Company logo URL
signalData:
type: object
description: Signal-specific data that varies by signal type
properties:
jobTitle:
type: string
description: '[companyIsHiring] Job posting title'
jobDescription:
type: string
description: '[companyIsHiring] Job posting description'
jobLocation:
type: string
description: '[companyIsHiring] Job posting location'
jobUrl:
type: string
description: '[companyIsHiring] Job posting URL'
jobStatus:
type: string
description: '[companyIsHiring] Job posting status'
websiteVisited:
type: string
description: '[companyEmployeeVisitedMyWebsite] Website URL that was visited'
visitorWebsite:
type: string
description: '[companyEmployeeVisitedMyWebsite] Visitor''s company website'
linkedinPostUrl:
type: string
description: '[linkedinProfile/linkedinTopic] URL of the LinkedIn post'
linkedinPostText:
type: string
description: >-
[linkedinProfile/linkedinTopic] Text content of the LinkedIn
post
linkedinReactionType:
type: string
description: >-
[linkedinProfile/linkedinTopic] Type of LinkedIn reaction (like,
comment, post)
linkedinReactedAt:
type: string
format: date-time
description: >-
[linkedinProfile/linkedinTopic] When the LinkedIn reaction
occurred
linkedinCommentText:
type: string
description: '[linkedinProfile/linkedinTopic] Text of the LinkedIn comment'
securitySchemes:
basicAuth:
type: http
scheme: basic
````