1eye Docs – Buyer Signals API, Webhooks, MCP & Integrations

Returns Signals belonging to the workspace associated with your API key.

GET /v1/signals

Request

curl "https://api.1eye.ai/v1/signals" \
  -H "Authorization: Bearer 1eye_live_xxxxxxxxx"

Query parameters

Parameter	Type	Description
`limit`	integer	Number of Signals to return. Default: `100`. Maximum: `1000`.
`cursor`	string	Cursor returned by the previous request for retrieving the next page.
`buyer_id`	string	Return Signals associated with a specific Buyer.
`type`	string	Filter by Signal type: `website`, `market`, or `linkedin`.
`trigger`	string	Filter by Signal trigger. `type` is required when using `trigger`.
`captured_after`	timestamp	Return Signals captured at or after this timestamp.
`captured_before`	timestamp	Return Signals captured before this timestamp.
`sort_by`	string	Field used to sort results. GET signals only supports `captured_at`.
`sort_order`	string	Sort direction. Supported values: `asc`, `desc`.

Filter by Signal type

Supported Signal types are:

website
market
linkedin

Website Signals:

curl "https://api.1eye.ai/v1/signals?type=website" \
  -H "Authorization: Bearer 1eye_live_xxxxxxxxx"

Market Signals:

curl "https://api.1eye.ai/v1/signals?type=market" \
  -H "Authorization: Bearer 1eye_live_xxxxxxxxx"

LinkedIn Signals:

curl "https://api.1eye.ai/v1/signals?type=linkedin" \
  -H "Authorization: Bearer 1eye_live_xxxxxxxxx"

Filter by trigger

Supported type and trigger combinations are:

Type	Supported triggers
`website`	`visited_page`, `filled_form`, `abandoned_form`
`market`	`researched_topic`, `explored_product`, `evaluated_competitor`
`linkedin`	`followed_page`, `commented_post`, `reacted_post`

If trigger is provided, type is required. Example:

curl "https://api.1eye.ai/v1/signals?type=website&trigger=visited_page" \
  -H "Authorization: Bearer 1eye_live_xxxxxxxxx"

LinkedIn comments:

curl "https://api.1eye.ai/v1/signals?type=linkedin&trigger=commented_post" \
  -H "Authorization: Bearer 1eye_live_xxxxxxxxx"

Filter by Buyer

Use buyer_id to retrieve Signals associated with a specific Buyer.

curl "https://api.1eye.ai/v1/signals?buyer_id=buy_123456789012345678" \
  -H "Authorization: Bearer 1eye_live_xxxxxxxxx"

Filters can be combined:

curl "https://api.1eye.ai/v1/signals?buyer_id=buy_123456789012345678&type=website&trigger=visited_page" \
  -H "Authorization: Bearer 1eye_live_xxxxxxxxx"

Multiple filters are combined using AND.

Filter by capture time

Use captured_after and captured_before to filter by when the Signal occurred.

curl "https://api.1eye.ai/v1/signals?captured_after=2026-09-01T00:00:00Z&captured_before=2026-10-01T00:00:00Z" \
  -H "Authorization: Bearer 1eye_live_xxxxxxxxx"

Time filters use inclusive-start and exclusive-end semantics:

captured_after  → captured_at >= value
captured_before → captured_at < value

Timestamps use UTC in ISO 8601 format:

YYYY-MM-DDTHH:mm:ssZ

Sort Signals

GET signals only supports captured_at. Most recently captured Signals first:

curl "https://api.1eye.ai/v1/signals?sort_by=captured_at&sort_order=desc" \
  -H "Authorization: Bearer 1eye_live_xxxxxxxxx"

Oldest Signals first:

curl "https://api.1eye.ai/v1/signals?sort_by=captured_at&sort_order=asc" \
  -H "Authorization: Bearer 1eye_live_xxxxxxxxx"

By default, Signals are returned in:

captured_at DESC
id DESC

The Signal ID is automatically used as a deterministic tie-breaker and does not need to be included in sort_by.

Pagination

Use limit to control the number of Signals returned in each request.

curl "https://api.1eye.ai/v1/signals?limit=100" \
  -H "Authorization: Bearer 1eye_live_xxxxxxxxx"

If additional results are available, the response includes a next_cursor. Pass that value using the cursor parameter:

curl "https://api.1eye.ai/v1/signals?limit=100&cursor=eyJ..." \
  -H "Authorization: Bearer 1eye_live_xxxxxxxxx"

Continue requesting pages until next_cursor is null.

Signal object

Every Signal uses the same top-level structure:

id
buyer_id
type
website
market
linkedin
captured_at
created_at
updated_at

The object corresponding to the Signal’s type is populated. The other type-specific objects are null. For example:

type: website → website is populated
type: market → market is populated
type: linkedin → linkedin is populated

Response

A successful request returns Signal objects in data. The example below shows one Signal of each type.

{
  "total": 3,
  "data": [
    {
      "id": "sig_123456789012345678",
      "buyer_id": "buy_123456789012345678",
      "type": "website",
      "website": {
        "trigger": "visited_page",
        "url": {
          "raw": "example.com/pricing?utm_source=google&utm_medium=cpc",
          "canonical": "example.com/pricing",
          "domain": "example.com",
          "path": "/pricing"
        },
        "attribution": {
          "type": "paid",
          "source": "google_ads",
          "source_name": "Google Ads",
          "source_logo": "https://example.com/google-ads.png"
        },
        "utm": {
          "source": "google",
          "medium": "cpc",
          "campaign": "brand",
          "term": "",
          "content": ""
        },
        "click_ids": {
          "gclid": "example_gclid",
          "gbraid": null,
          "wbraid": null,
          "dclid": null,
          "li_fat_id": null,
          "msclkid": null,
          "fbclid": null,
          "ttclid": null,
          "twclid": null
        },
        "target_page": {
          "id": "tpg_123456789012345678",
          "name": "Pricing Page",
          "short_name": "PRICING",
          "description": ""
        },
        "session": {
          "id": "sess_example123",
          "started_at": "2026-09-25T18:20:00Z",
          "ended_at": "2026-09-25T18:22:00Z",
          "duration_secs": 120
        },
        "device": {
          "browser": "Chrome",
          "browser_version": "152.0.0.0",
          "os": "macOS",
          "os_version": "26.6",
          "device_type": "desktop",
          "language": "en-US"
        },
        "location": {
          "ip": "203.0.113.10",
          "city": "San Francisco",
          "state": "California",
          "country": "United States",
          "country_code": "US",
          "postal_code": "94105",
          "latitude": 37.7749,
          "longitude": -122.4194,
          "timezone": "America/Los_Angeles"
        },
        "page": {
          "visited_at": "2026-09-25T18:21:00Z",
          "time_spent_secs": 120,
          "visit_count": 3,
          "first_visited_at": "2026-09-20T17:00:00Z",
          "last_visited_at": "2026-09-25T18:21:00Z",
          "total_time_spent_secs": 420
        }
      },
      "market": null,
      "linkedin": null,
      "captured_at": "2026-09-25T18:21:00Z",
      "created_at": "2026-09-25T18:22:01Z",
      "updated_at": "2026-09-25T18:22:01Z"
    },
    {
      "id": "sig_234567890123456789",
      "buyer_id": "buy_234567890123456789",
      "type": "market",
      "website": null,
      "market": {
        "trigger": "explored_product",
        "attribution": {
          "type": "in_market",
          "source": "product_intent",
          "source_name": "Product Intent",
          "source_logo": ""
        },
        "topic": "sales prioritization",
        "company_website": "https://example.com/"
      },
      "linkedin": null,
      "captured_at": "2026-09-24T06:40:57Z",
      "created_at": "2026-09-24T06:40:15Z",
      "updated_at": "2026-09-24T06:40:57Z"
    },
    {
      "id": "sig_345678901234567890",
      "buyer_id": "buy_345678901234567890",
      "type": "linkedin",
      "website": null,
      "market": null,
      "linkedin": {
        "trigger": "reacted_post",
        "attribution": {
          "type": "social",
          "source": "linkedin_reaction",
          "source_name": "LinkedIn Reaction",
          "source_logo": ""
        },
        "source": "linkedin",
        "url": "https://www.linkedin.com/posts/example-post",
        "comment": "",
        "reaction_type": "like",
        "company_name": "",
        "post_title": ""
      },
      "captured_at": "2026-09-14T19:10:17Z",
      "created_at": "2026-09-14T19:09:42Z",
      "updated_at": "2026-09-14T19:10:17Z"
    }
  ],
  "pagination": {
    "next_cursor": null
  }
}

The type-specific objects contain different fields depending on the Signal source: Website Signals can include URL, attribution, UTM parameters, advertising click IDs, Target Page details, session information, device information, location, and page engagement data. Market Signals include the Market trigger, attribution, intent topic, and company website. LinkedIn Signals include the LinkedIn trigger, attribution, LinkedIn URL, comment or reaction data, and related company or post information. The production response uses this same top-level polymorphic structure.

Errors

Status	Error Code	Description
`400`	`invalid_parameter`	An unsupported or invalid query parameter was provided
`400`	`invalid_cursor`	The pagination cursor is invalid or does not match the request
`401`	`authentication_error`	The API key is missing, invalid, or revoked
`429`	`rate_limit_exceeded`	The workspace has exceeded an API rate limit
`500`	`internal_error`	An unexpected server error occurred
`503`	`service_unavailable`	The API is temporarily unavailable

Get Started

Buyers

Signals

List Signals

Request

Query parameters

Filter by Signal type

Filter by trigger

Filter by Buyer

Filter by capture time

Sort Signals

Signal object

Response

Errors

​Request

​Query parameters

​Filter by Signal type

​Filter by trigger

​Filter by Buyer

​Filter by capture time

​Sort Signals

​Pagination

​Signal object

​Response

​Errors

Request

Query parameters

Filter by Signal type

Filter by trigger

Filter by Buyer

Filter by capture time

Sort Signals

Pagination

Signal object

Response

Errors