# Monitoring the network

Enable network monitoring once, then poll a single endpoint to receive connection events — accepted requests, new connections, and incoming connection requests — as they happen.

Network monitoring lets you track changes to an account's connection graph in the background, instead of repeatedly retrieving connections and pending requests and diffing them yourself. It involves 2 key steps:

1. **Enabling**. Enable network sync once per account. From that point on, Linked API watches the account's network in the background and captures connection events.
2. **Polling**. After network sync is enabled, poll a single endpoint to retrieve captured events and receive new ones — **without retrieving the whole connection list each time**.

> 💡 **Monitoring does not import history.** Only changes that happen **after** you enable it are captured — your existing connections and pending invitations are used as a silent baseline and never emitted. When you need the state as it is right now (a full list, a one-off audit, backfilling before monitoring was on), reach for [`st.retrieveConnections`](/docs/action-st-retrieve-connections) and [`st.retrieveInvitations`](/docs/action-st-retrieve-invitations) instead.

## Enabling

[Execute a workflow](/docs/executing-workflows) with the [`st.syncNetwork`](/docs/action-st-sync-network) action. You only need to do this once per account.

**Workflow:**

```json
{
  "actionType": "st.syncNetwork"
}
```

**Completion:**

```json
{
  "actionType": "st.syncNetwork",
  "success": true
}
```

## Event types

Network monitoring emits three kinds of events:

- `connectionRequestReceived` – someone sent **you** a connection request. A new incoming pending invitation was observed.
- `connectionAccepted` – a new connection that matches a request **you** sent. The other person accepted your outgoing invitation.
- `connectionAdded` – a new connection that is **not** attributable to a request you sent. For example, you accepted someone else's incoming request, or the connection was formed outside the API.

> 💡 Together, `connectionAccepted` and `connectionAdded` cover every new first-degree connection: `connectionAccepted` is the subset you initiated, `connectionAdded` is everything else. If you only care that the network grew, handle both.

## Polling

Unlike enabling, you don't execute workflows to poll the network. Instead, send a `POST` request to the following endpoint:

```text
POST https://api.linkedapi.io/network/poll
```

The request body is a single object. All fields are optional:

```json
{
  "since": "2023-01-01T00:00:00Z",
  "type": "connectionAccepted"
}
```

- `since` (optional) – timestamp indicating the starting point for retrieving events. If not provided, all captured events are returned.
- `type` (optional) – filter by a single event type. If omitted, all event types are returned:
  - `connectionRequestReceived`
  - `connectionAccepted`
  - `connectionAdded`

If your request is correct, you will receive the following response:

```json
{
  "success": true,
  "result": {
    "events": [
      {
        "id": "f4d92946-8821-6da6-ff4c-c36f0671292a",
        "type": "connectionAccepted",
        "personUrl": "https://www.linkedin.com/in/person1",
        "detectedAt": "2023-01-02T10:35:00Z"
      },
      {
        "id": "2a1b7f25-daba-5e20-70e9-c6427bb4f660",
        "type": "connectionRequestReceived",
        "personUrl": "https://www.linkedin.com/in/person2",
        "detectedAt": "2023-01-02T09:12:00Z"
      }
    ]
  }
}
```

- `events` – array of connection events, ordered newest first.
  - `id` – unique identifier for the event.
  - `type` – one of `connectionRequestReceived`, `connectionAccepted`, or `connectionAdded`.
  - `personUrl` – LinkedIn URL of the other person.
  - `detectedAt` – timestamp when Linked API observed the event.

**Recommended flow for integrations:**

1. Leave `since` empty on the first request to retrieve everything captured so far.
2. For subsequent requests, pass the **timestamp of the most recent event** you received as `since` to fetch only newer events.
3. Continue polling with an advancing `since`. Whenever new events arrive, update `since` to the latest `detectedAt`.

> Events are retained for **90 days**. Poll (or receive webhooks) often enough to consume them within that window — older events are pruned and will no longer be returned.

> 💡 For push-based delivery instead of polling, subscribe to the network [Webhook Events](/docs/webhooks). They fire for accounts with network monitoring enabled and carry the same event fields.

> This page provides examples of [workflows](/docs/building-workflows) and their [completions](/docs/executing-workflows). For detailed documentation on constraints, parameters, and possible results of specific actions, always refer to the corresponding [action documentation pages](/docs/actions-overview).