# Events

URL: https://submitator.com/docs/api/events

> Every change to your projects, listings and reports, in order.

Every change to your projects, listings and reports, in order. Events are kept for 90 days. Read the feed with a cursor to keep your records in sync, or receive the same events as webhooks.

An event's `created_at` is exact to the second and shows when the change was recorded, within about a minute of the change itself. Listing times inside the event stay rounded down to the hour.

The feed has no gaps: a cursor returns every event recorded after it, in order. Each change sends one event, and a launch sends `project.launched` once instead of one event per new listing.

## List events

`GET https://api.submitator.com/v1/events`

Returns every change to your projects, listings and reports, oldest first. Store `next_cursor` and send it back as `cursor` to read only what is new; it is never `null` here. Filter by `type` or `project`.

| Parameter | In | Required | What it is |
| --- | --- | --- | --- |
| `cursor` | query | No | `next_cursor` from your last call. Leave it out to start at the oldest event kept (90 days). A cursor older than that returns 410 `cursor_expired`. |
| `type` | query | No | Only events of this type. Use a type such as `listing.live`, or a group such as `listing.*`, `project.*` or `report.*`. |
| `project` | query | No | Only events about this project. |
| `limit` | query | No | How many items to return, 1 to 100. Defaults to 20. |

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "event",
      "id": "evt_6Lr3Kx8Wq2Nt7Vb1Rz5MpA",
      "type": "listing.action_required",
      "created_at": "2026-10-08T09:13:30Z",
      "livemode": false,
      "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP",
      "data": {
        "object": {
          "object": "listing",
          "id": "lst_2Tz6Kp9Wm3Qx8Lr5Vb1NcJ",
          "livemode": false,
          "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP",
          "directory": {
            "id": "dir_3Vb8Qm2Xk6Lt9Wr4Nc1ZpG",
            "name": "Uneed",
            "domain_rating": 58,
            "logo_url": "https://feed.example.net/a/u7Nd3Kc.w5Rb"
          },
          "status": "action_required",
          "reason": null,
          "action": {
            "code": "install_badge",
            "waiting_on": "client",
            "client_message": "Please add the directory badges block to https://ledgerly.test. Uneed lists Ledgerly once its badge shows on the site."
          },
          "live_url": null,
          "proof_url": null,
          "created_at": "2026-10-04T10:00:00Z",
          "submitted_at": null,
          "live_at": null
        },
        "previous_status": "in_progress"
      }
    },
    {
      "object": "event",
      "id": "evt_6Mz4Kq9Wr3Lt8Vb2Nx6HcE",
      "type": "project.action_required",
      "created_at": "2026-10-08T09:13:30Z",
      "livemode": false,
      "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP",
      "data": {
        "object": {
          "object": "project",
          "id": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP",
          "livemode": false,
          "status": "action_required",
          "hold_reason": null,
          "action": {
            "code": "install_badge",
            "waiting_on": "client",
            "client_message": "Please add the directory badges block to https://ledgerly.test. 9 directories list Ledgerly once their badges show on the site."
          },
          "url": "https://ledgerly.test",
          "name": "Ledgerly",
          "maker_name": "Maya Chen",
          "contact_email": "founder@ledgerly.test",
          "tagline": "Double-entry bookkeeping for solo founders",
          "short_description": "Ledgerly keeps the books for one-person companies: bank sync, invoices and a year-end pack for your accountant.",
          "long_description": null,
          "category": "saas",
          "pricing_model": "freemium",
          "price_amount_cents": 1200,
          "price_period": "monthly",
          "launch_date": null,
          "twitter_url": null,
          "competitors": [],
          "tags": [
            "accounting",
            "bookkeeping",
            "invoicing"
          ],
          "audience": {
            "b2b": false,
            "ai": false,
            "directory": false
          },
          "promo_code": null,
          "promo_description": null,
          "logo": {
            "object": "image",
            "id": "img_5Mx2Kq8Wt3Lr9Vb7Nz1HdQ",
            "status": "ready",
            "url": "https://feed.example.net/a/Lq7Wx2Km.r9Tz4",
            "error": null
          },
          "screenshots": [
            {
              "object": "image",
              "id": "img_2Kr9Lx3Wq7Mt5Vb8Nz1HcF",
              "status": "ready",
              "url": "https://feed.example.net/a/Sv3Nk8Qp.m2Wx7",
              "error": null
            }
          ],
          "autofill": {
            "status": "complete",
            "name_source": "site",
            "filled": [
              "name",
              "tagline",
              "short_description"
            ],
            "image_candidates": [
              {
                "url": "https://ledgerly.test/apple-touch-icon.png",
                "suggested_as": "logo",
                "width": 180,
                "height": 180
              },
              {
                "url": "https://ledgerly.test/og-image.png",
                "suggested_as": "screenshot",
                "width": 1200,
                "height": 630
              }
            ]
          },
          "readiness": {
            "ready": true,
            "missing": []
          },
          "domain_rating": 34,
          "badge": {
            "status": "not_found",
            "checked_at": "2026-10-08T09:12:44Z"
          },
          "auto_replace": true,
          "excluded_directories": [],
          "allowance": {
            "total": 100,
            "used": 78,
            "reserved": 14,
            "available": 8
          },
          "progress": {
            "total": 96,
            "pending": 0,
            "in_progress": 5,
            "action_required": 9,
            "submitted": 9,
            "live": 69,
            "not_accepted": 3,
            "cancelled": 1
          },
          "external_id": "crm_8812",
          "metadata": {
            "account_owner": "Priya",
            "crm_stage": "onboarding"
          },
          "created_at": "2026-10-03T13:58:12Z",
          "updated_at": "2026-10-08T09:13:30Z",
          "launched_at": "2026-10-03T14:05:40Z"
        },
        "previous_status": "in_progress"
      }
    },
    {
      "object": "event",
      "id": "evt_5Rt8Wq2Lm7Xn3Kb9Vz1PdJ",
      "type": "listing.live",
      "created_at": "2026-10-08T14:17:01Z",
      "livemode": false,
      "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP",
      "data": {
        "object": {
          "object": "listing",
          "id": "lst_7Hk2Qn4Rt9Vx1Bm6Cz3LdK",
          "livemode": false,
          "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP",
          "directory": {
            "id": "dir_2Lm8Wq3Zk7Rt1Xc5Vb9NdF",
            "name": "BetaList",
            "domain_rating": 73,
            "logo_url": "https://feed.example.net/a/x1Lq7Rt.k9Zm"
          },
          "status": "live",
          "reason": null,
          "action": null,
          "live_url": "https://betalist.com/startups/ledgerly",
          "proof_url": "https://feed.example.net/a/Pf8Kq2Wm.t6Lx9",
          "created_at": "2026-10-03T14:00:00Z",
          "submitted_at": "2026-10-04T09:00:00Z",
          "live_at": "2026-10-08T14:00:00Z"
        },
        "previous_status": "submitted"
      }
    }
  ],
  "has_more": false,
  "next_cursor": "cur_Ev7Kq2Wx9Lt3Nb5R"
}
```

Typical errors: [`invalid_cursor`](https://submitator.com/docs/errors#invalid_cursor), [`cursor_expired`](https://submitator.com/docs/errors#cursor_expired), [`validation_failed`](https://submitator.com/docs/errors#validation_failed).

## Read an event

`GET https://api.submitator.com/v1/events/{event_id}`

Returns one event from the last 90 days. A webhook delivery's `webhook-id` header is the event id, so you can fetch the event to confirm a delivery came from us.

| Parameter | In | Required | What it is |
| --- | --- | --- | --- |
| `event_id` | path | Yes | The event's id, which is also the `webhook-id` header of its deliveries. |

Response 200:

```json
{
  "object": "event",
  "id": "evt_5Rt8Wq2Lm7Xn3Kb9Vz1PdJ",
  "type": "listing.live",
  "created_at": "2026-10-08T14:17:01Z",
  "livemode": false,
  "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP",
  "data": {
    "object": {
      "object": "listing",
      "id": "lst_7Hk2Qn4Rt9Vx1Bm6Cz3LdK",
      "livemode": false,
      "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP",
      "directory": {
        "id": "dir_2Lm8Wq3Zk7Rt1Xc5Vb9NdF",
        "name": "BetaList",
        "domain_rating": 73,
        "logo_url": "https://feed.example.net/a/x1Lq7Rt.k9Zm"
      },
      "status": "live",
      "reason": null,
      "action": null,
      "live_url": "https://betalist.com/startups/ledgerly",
      "proof_url": "https://feed.example.net/a/Pf8Kq2Wm.t6Lx9",
      "created_at": "2026-10-03T14:00:00Z",
      "submitted_at": "2026-10-04T09:00:00Z",
      "live_at": "2026-10-08T14:00:00Z"
    },
    "previous_status": "submitted"
  }
}
```

Typical errors: [`not_found`](https://submitator.com/docs/errors#not_found), [`rate_limited`](https://submitator.com/docs/errors#rate_limited).