---
updatedAt: 2026-08-25T15:12:32.000Z
agentTools:
  projectIndex: https://docs.greynoise.io/llms.txt
---

# Acknowledge a processed feed-event batch

Advance the named consumer's server-held checkpoint to the signed cursor
returned by the fetch endpoint. Acknowledge only after the complete batch
has been processed successfully.

Acknowledgement is the only operation that advances pull state. Repeating
an acknowledgement or acknowledging an older cursor is a safe no-op and
never moves the checkpoint backward. The `advanced` response field reports
whether this request moved it forward.


# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "description": "GreyNoise is a cybersecurity company that collects and analyzes Internet-wide scan and attack traffic. Use GreyNoise to contextualize existing alerts, filter false-positives, identify compromised devices, and track emerging threats.",
    "version": "3.0.0",
    "title": "GreyNoise API",
    "contact": {
      "email": "hello@greynoise.io"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://www.greynoise.io/terms"
    }
  },
  "tags": [
    {
      "name": "Event Feeds",
      "description": "Consume and search workspace-scoped feed events retained for approximately\n90 days.\n\nPull consumers keep their checkpoints on the server. Fetching is read-only;\nacknowledge the returned signed cursor only after processing the complete\nbatch. Event search uses a separate stateless pagination cursor and never\nchanges a pull consumer's checkpoint.\n\nSession events are webhook-only and are not retained, searchable, or\navailable through the pull API. Access depends on the workspace's Feeds and\nEvent Feed API entitlements.\n\nFor an end-to-end integration workflow, see\n[Using the Feeds API to Retrieve Events](https://docs.greynoise.io/docs/using-the-feeds-api-to-retrieve-events).\n"
    }
  ],
  "security": [
    {
      "APIKeyHeaderAuth": []
    }
  ],
  "paths": {
    "/v3/feeds/{feed_id}/events/ack": {
      "post": {
        "tags": [
          "Event Feeds"
        ],
        "operationId": "AcknowledgeFeedEvents",
        "summary": "Acknowledge a processed feed-event batch",
        "description": "Advance the named consumer's server-held checkpoint to the signed cursor\nreturned by the fetch endpoint. Acknowledge only after the complete batch\nhas been processed successfully.\n\nAcknowledgement is the only operation that advances pull state. Repeating\nan acknowledgement or acknowledging an older cursor is a safe no-op and\nnever moves the checkpoint backward. The `advanced` response field reports\nwhether this request moved it forward.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/eventFeedId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EventFeedAcknowledgeRequest"
              },
              "example": {
                "consumer": "scheduled-lambda",
                "cursor": "eyJ2IjoxLCJ3IjoiLi4uIn0.signature"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The consumer's current checkpoint after acknowledgement.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventFeedAcknowledgeResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/EventFeedBadRequest"
          },
          "401": {
            "$ref": "#/components/responses/EventFeedUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/EventFeedForbidden"
          },
          "404": {
            "$ref": "#/components/responses/EventFeedNotFound"
          },
          "408": {
            "$ref": "#/components/responses/EventFeedRequestTimeout"
          },
          "409": {
            "$ref": "#/components/responses/EventFeedConflict"
          },
          "410": {
            "$ref": "#/components/responses/EventFeedGone"
          },
          "500": {
            "$ref": "#/components/responses/EventFeedUnexpectedError"
          },
          "502": {
            "$ref": "#/components/responses/EventFeedBadGateway"
          },
          "504": {
            "$ref": "#/components/responses/EventFeedGatewayTimeout"
          }
        }
      }
    }
  },
  "servers": [
    {
      "url": "https://api.greynoise.io"
    },
    {
      "url": "http://api.greynoise.io"
    }
  ],
  "components": {
    "securitySchemes": {
      "APIKeyHeaderAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "key"
      }
    },
    "responses": {
      "EventFeedBadRequest": {
        "description": "A path parameter, query parameter, request body, filter, or cursor is invalid.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/EventFeedError"
            },
            "example": {
              "error": "bad request",
              "code": 400
            }
          }
        }
      },
      "EventFeedUnauthorized": {
        "description": "The API key or authenticated user is missing or invalid.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/EventFeedError"
            },
            "example": {
              "error": "unauthorized",
              "code": 401
            }
          }
        }
      },
      "EventFeedForbidden": {
        "description": "The caller cannot access the workspace or the required entitlement is not enabled.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/EventFeedError"
            },
            "example": {
              "error": "event feed API entitlement required",
              "code": 403
            }
          }
        }
      },
      "EventFeedNotFound": {
        "description": "The workspace-scoped feed or consumer was not found.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/EventFeedError"
            },
            "example": {
              "error": "not found",
              "code": 404
            }
          }
        }
      },
      "EventFeedRequestTimeout": {
        "description": "The request was canceled before it completed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/EventFeedError"
            },
            "example": {
              "error": "request timeout",
              "code": 408
            }
          }
        }
      },
      "EventFeedConflict": {
        "description": "The requested consumer conflicts with existing state, or the feed has\nreached its durable-consumer limit.\n",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/EventFeedError"
            },
            "example": {
              "error": "conflict",
              "code": 409
            }
          }
        }
      },
      "EventFeedGone": {
        "description": "The cursor points outside the retained event window. Follow the returned\nrecovery action to fetch from the current retention boundary.\n",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/EventFeedError"
            },
            "examples": {
              "acknowledgeCursorExpired": {
                "summary": "An acknowledgement cursor has fallen outside retention",
                "value": {
                  "error": "gone",
                  "code": 410,
                  "recovery": {
                    "action": "fetch_without_cursor"
                  }
                }
              },
              "searchCursorExpired": {
                "summary": "A search cursor has fallen outside retention",
                "value": {
                  "error": "gone",
                  "code": 410,
                  "recovery": {
                    "action": "restart_search"
                  }
                }
              }
            }
          }
        }
      },
      "EventFeedUnexpectedError": {
        "description": "An unexpected error occurred while processing the request.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/EventFeedError"
            },
            "example": {
              "error": "internal server error",
              "code": 500
            }
          }
        }
      },
      "EventFeedBadGateway": {
        "description": "The Event Feed service was unavailable or returned an invalid response.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/EventFeedError"
            },
            "example": {
              "error": "bad gateway",
              "code": 502
            }
          }
        }
      },
      "EventFeedGatewayTimeout": {
        "description": "The Event Feed service did not complete the request before its deadline.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/EventFeedError"
            },
            "example": {
              "error": "gateway timeout",
              "code": 504
            }
          }
        }
      }
    },
    "parameters": {
      "eventFeedId": {
        "name": "feed_id",
        "in": "path",
        "description": "Feed UUID. The feed must belong to the authenticated workspace.",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      }
    },
    "schemas": {
      "EventFeedError": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "error",
          "code"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "Safe, human-readable error message."
          },
          "code": {
            "type": "integer",
            "description": "HTTP status code."
          },
          "recovery": {
            "$ref": "#/components/schemas/EventFeedRecovery"
          }
        }
      },
      "EventFeedRecovery": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "action"
        ],
        "properties": {
          "action": {
            "type": "string",
            "description": "Recovery action for a cursor that has fallen outside retention.",
            "enum": [
              "fetch_without_cursor",
              "restart_search"
            ]
          }
        }
      },
      "EventFeedAcknowledgeRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "cursor"
        ],
        "properties": {
          "cursor": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2048,
            "description": "Signed cursor returned by the feed-event fetch endpoint."
          },
          "consumer": {
            "allOf": [
              {
                "$ref": "#/components/schemas/EventFeedConsumerName"
              }
            ],
            "default": "default",
            "description": "Must identify the same consumer used to fetch the batch."
          }
        }
      },
      "EventFeedAcknowledgeResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "consumer",
          "cursor",
          "acknowledged_at",
          "updated_at",
          "advanced"
        ],
        "properties": {
          "consumer": {
            "$ref": "#/components/schemas/EventFeedConsumerName"
          },
          "cursor": {
            "type": "string",
            "maxLength": 2048,
            "description": "Signed representation of the consumer's current checkpoint."
          },
          "acknowledged_at": {
            "type": "string",
            "format": "date-time",
            "description": "Creation time of the event at the current checkpoint."
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "Time the server-held checkpoint was last advanced."
          },
          "advanced": {
            "type": "boolean",
            "description": "Whether this request moved the checkpoint forward."
          }
        }
      },
      "EventFeedConsumerName": {
        "type": "string",
        "minLength": 1,
        "maxLength": 128,
        "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$",
        "description": "Stable consumer name beginning with an alphanumeric character and\ncontaining only alphanumerics, period, underscore, or hyphen.\n",
        "example": "scheduled-lambda"
      }
    }
  }
}
```