> ## Documentation Index
> Fetch the complete documentation index at: https://docs.incident.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Follow-ups API

> Programmatic access to your follow-ups, with pagination and filters built for syncing them into your own tools.

Everything you can see in the follow-ups list view is also available through our public API. Use it to sync follow-ups into a data warehouse, mirror them in an internal tracker, or build reporting that we don't offer natively.

## What you can do

The [Follow-ups V3 API](/api-reference/follow-ups-v3) covers the full lifecycle of a follow-up:

### List and filter follow-ups

You can [list follow-ups](/api-reference/follow-ups-v3/list) across your organization. Results are paginated, and you can filter by incident, assignee team, and the `created_at` and `updated_at` timestamps. The timestamp filters are what make incremental syncing possible, which we cover below.

### Create and update follow-ups

You can [create follow-ups](/api-reference/follow-ups-v3/create) against an incident, [update them](/api-reference/follow-ups-v3/update) (title, description, status, assignee, priority, labels), and [delete them](/api-reference/follow-ups-v3/delete). Use the [show endpoint](/api-reference/follow-ups-v3/show) to fetch a single follow-up.

### Connect external issues

If you track follow-up work in your issue tracker, you can [connect a follow-up to an existing issue](/api-reference/follow-ups-v3/connectexternalissue) by its URL. The follow-up then carries a reference to that issue, and we keep its status in sync.

## Keeping follow-ups in sync

The most common use of this API is keeping an external system up to date with your follow-ups. Rather than re-fetching everything on a schedule, do an initial full import and then poll for changes.

For the initial import, page through the full list:

```bash theme={null}
curl --get 'https://api.incident.io/v3/follow_ups' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --data 'page_size=250'
```

Each response includes a `pagination_meta` object. If it contains an `after` cursor, pass that to the next request to get the next page. When `after` is missing, you have reached the end.

From then on, poll with `updated_at[gte]` set to when you last synced:

```bash theme={null}
curl --get 'https://api.incident.io/v3/follow_ups' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --data 'updated_at[gte]=2025-01-01T00:00:00Z'
```

This returns only the follow-ups that changed since your last sync, so a poll usually returns a handful of rows instead of your whole history.

Two things to account for in your sync logic:

* **Overlap your window.** Timestamps are stamped just before a write commits, so a follow-up can occasionally become visible with an `updated_at` slightly older than rows you have already seen. Set your `updated_at[gte]` bound a few minutes earlier than your last sync time and treat re-fetched rows as upserts.
* **Embedded objects don't bump `updated_at`.** The timestamp moves when the follow-up itself changes. Changes to things embedded in the payload, like an assignee being renamed or an external issue's status text, don't move it. If you need those fresh too, run an occasional full re-sync.

## Getting started

Check out our [API reference](/api-reference/introduction) for the full details on authentication, pagination, and response formats. Here are the direct links to the follow-up endpoints:

* [List follow-ups](/api-reference/follow-ups-v3/list)
* [Show a follow-up](/api-reference/follow-ups-v3/show)
* [Create a follow-up](/api-reference/follow-ups-v3/create)
* [Update a follow-up](/api-reference/follow-ups-v3/update)
* [Delete a follow-up](/api-reference/follow-ups-v3/delete)
* [Connect an external issue](/api-reference/follow-ups-v3/connectexternalissue)