From b0268b1d3485d95ff361a9ee0df09728a39baf8c Mon Sep 17 00:00:00 2001
From: aviau <alexandre@alexandreviau.net>
Date: Wed, 19 Nov 2025 18:31:26 -0500
Subject: [PATCH] sdk: document scroll_events

---
 docs/changelog/overview.mdx | 11 ++++++++++
 docs/sdk/python.mdx         | 44 +++++++++++++++++++++++++++++++++++--
 requirements.txt            |  2 +-
 3 files changed, 54 insertions(+), 3 deletions(-)

diff --git a/docs/changelog/overview.mdx b/docs/changelog/overview.mdx
index b54cc42..a259c40 100644
--- a/docs/changelog/overview.mdx
+++ b/docs/changelog/overview.mdx
@@ -12,6 +12,17 @@ This page lists changes to Flare's API.
 Release notes for the Flare Platform can be found on the [product documentation website](https://docs.flare.io/releases).
 </Note>
 
+<Update label="2025-11-19" description="Python SDK - v1.2.0">
+  Released version 1.2.0 of the
+  [Python SDK <Icon icon="book" size={16} />](/sdk/python).
+
+  This release adds a new `scroll_events` method that can be used to retrieve events from the feed APIs
+  without having to manage fetching events individually.
+  
+  More information, including full examples, can be found in the
+  [Python SDK documentation <Icon icon="book" size={16} />](/sdk/python).
+</Update>
+
 <Update label="2025-11" description="API - November 2025">
   Added a [Global Search Credentials Endpoint <Icon icon="code" size={16} />](/api-reference/v4/endpoints/credentials-global-search).
   This new endpoint allows for searching in all of Flare's credentials and counts towards the Global Search quota.
diff --git a/docs/sdk/python.mdx b/docs/sdk/python.mdx
index ab28aff..a1b76b3 100644
--- a/docs/sdk/python.mdx
+++ b/docs/sdk/python.mdx
@@ -58,12 +58,12 @@ resp = client.get("/tokens/test")
 print(resp.json())
 ```
 
-## Paging Util
+## Paging Util - Generic
 
 The `FlareApiClient` has a `scroll` method that can be used with endpoints that support the
 [Flare standard paging pattern <Icon icon="book" size={16} />](/concepts/paging).
 
-```python Paging Util Example
+```python Paging Util - Generic Example
 import os
 import time
 
@@ -102,6 +102,46 @@ for resp in api_client.scroll(
 print("The last value for 'next' was", last_from)
 ```
 
+## Paging Util - Event Feeds
+
+The `FlareApiClient` has a `scroll_events` method that can be used with event feeds endpoints.
+The advantage of this method over `scroll` is that it also automates the fetching of individual events.
+
+```python Paging Util - Event Feeds Example
+import datetime
+
+from flareio import FlareApiClient
+
+
+api_client = FlareApiClient.from_env()
+initial_cursor = None
+
+from_timestamp: str = (
+    datetime.datetime.now(tz=datetime.timezone.utc) - datetime.timedelta(hours=1)
+).isoformat()
+
+for event, next_cursor in api_client.scroll_events(
+    method="POST",
+    pages_url="/firework/v4/events/global/_search",
+    events_url="/firework/v2/activities/",
+    json={
+        "size": 10,
+        "order": "asc",
+        "from": initial_cursor,
+        "filters": {
+            "type": ["chat_message"],
+            "estimated_created_at": {"gte": from_timestamp},
+        },
+        "query": {
+            "type": "query_string",
+            "query_string": "hello",
+        },
+    },
+):
+    print(f"Full event data: {event}")
+    print(f"The next execution could resume using from={next_cursor}")
+```
+
 ## Custom Session
 
 The `FlareApiClient` can be initialized with a custom `requests.Session`. This allows, for example,
diff --git a/requirements.txt b/requirements.txt
index a9fa581..eefa1c1 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -5,4 +5,4 @@ python-frontmatter==1.1.0
 requests==2.32.5
 pytest==8.4.2
 types-requests==2.32.4.20250913
-flareio>=1.1.0
+flareio>=1.2.0