hotfix: support all subscriptions api results endpoint query parameters

docs/cli/cli-subscriptions.md

@@ -228,12 +228,50 @@ planet subscriptions results SUBSCRIPTION_ID
 By default this displays the first 100 results. As with other commands, you can use the `--limit` param to
 set a higher limit, or set it to 0 to see all results (this can be quite large with subscriptions results).
 
-You can also filter by status:
+#### Filtering Results
+
+The `results` command supports filtering on several fields:
+
+* `--status`: Filter on the status of results. Status options include `created`, `queued`, `processing`, `failed`, and `success`. Multiple status args are allowed.
+* `--created`: Filter results by creation time or an interval of creation times.
+* `--updated`: Filter results by update time or an interval of update times.
+* `--completed`: Filter results by completion time or an interval of completion times.
+* `--user-id`: Filter by user ID. Only available to organization admins. Accepts "all" or a specific user ID.
+
+Datetime args (`--created`, `--updated`, and `--completed`) can either be a date-time or an interval, open or closed. Date and time expressions adhere to RFC 3339. Open intervals are expressed using double-dots.
+
+* A date-time: `2018-02-12T23:20:50Z`
+* A closed interval: `2018-02-12T00:00:00Z/2018-03-18T12:31:12Z`
+* Open intervals: `2018-02-12T00:00:00Z/..` or `../2018-03-18T12:31:12Z`
+
+Examples:
+
+To see results that are currently processing:
 
 ```sh
 planet subscriptions results SUBSCRIPTION_ID --status processing
 ```
 
+To see successful results completed in the last week:
+
+```sh
+planet subscriptions results SUBSCRIPTION_ID --status success \
+    --completed 2026-03-17T00:00:00Z/..
+```
+
+To see results created in a specific time range:
+
+```sh
+planet subscriptions results SUBSCRIPTION_ID \
+    --created 2024-01-01T00:00:00Z/2024-02-01T00:00:00Z
+```
+
+To see results for all users in your organization (organization admin only):
+
+```sh
+planet subscriptions results SUBSCRIPTION_ID --user-id all
+```
+
 See the Subscriptions API documentation for the [official list of available statuses](https://docs.planet.com/develop/apis/subscriptions/#states--status-descriptions).
 
 #### Results as comma-separated values (CSV)

planet/cli/subscriptions.py

@@ -437,11 +437,21 @@ async def get_subscription_cmd(ctx, subscription_id, pretty):
               default=False,
               help="Get subscription results as comma-separated fields. When "
               "this flag is included, --limit is ignored")
+@click.option(
+    '--created',
+    help="""Filter results by creation time or interval. See documentation
+    for examples.""")
+@click.option(
+    '--updated',
+    help="""Filter results by update time or interval. See documentation
+    for examples.""")
+@click.option(
+    '--completed',
+    help="""Filter results by completion time or interval. See documentation
+    for examples.""")
+@click.option('--user-id',
+              help="Filter by user ID. Accepts 'all' or a specific user ID.")
 @limit
-# TODO: the following 3 options.
-# –created: timestamp instant or range.
-# –updated: timestamp instant or range.
-# –completed: timestamp instant or range.
 @click.pass_context
 @translate_exceptions
 @coro
@@ -450,6 +460,10 @@ async def list_subscription_results_cmd(ctx,
                                         pretty,
                                         status,
                                         csv_flag,
+                                        created,
+                                        updated,
+                                        completed,
+                                        user_id,
                                         limit):
     """Print the results of a subscription to stdout.
 
@@ -474,12 +488,20 @@ async def list_subscription_results_cmd(ctx,
     async with subscriptions_client(ctx) as client:
         if csv_flag:
             async for result in client.get_results_csv(subscription_id,
-                                                       status=status):
+                                                       status=status,
+                                                       created=created,
+                                                       updated=updated,
+                                                       completed=completed,
+                                                       user_id=user_id):
                 click.echo(result)
         else:
             async for result in client.get_results(subscription_id,
                                                    status=status,
-                                                   limit=limit):
+                                                   limit=limit,
+                                                   created=created,
+                                                   updated=updated,
+                                                   completed=completed,
+                                                   user_id=user_id):
                 echo_json(result, pretty)
 
 

planet/clients/subscriptions.py

@@ -514,15 +514,19 @@ async def get_subscription(self, subscription_id: str) -> dict:
             sub = resp.json()
             return sub
 
-    async def get_results(self,
-                          subscription_id: str,
-                          status: Optional[Sequence[Literal[
-                              "created",
-                              "queued",
-                              "processing",
-                              "failed",
-                              "success"]]] = None,
-                          limit: int = 100) -> AsyncIterator[dict]:
+    async def get_results(
+            self,
+            subscription_id: str,
+            status: Optional[Sequence[Literal["created",
+                                              "queued",
+                                              "processing",
+                                              "failed",
+                                              "success"]]] = None,
+            limit: int = 100,
+            created: Optional[str] = None,
+            updated: Optional[str] = None,
+            completed: Optional[str] = None,
+            user_id: Optional[Union[str, int]] = None) -> AsyncIterator[dict]:
         """Iterate over results of a Subscription.
 
         Notes:
@@ -536,6 +540,20 @@ async def get_results(self,
                 filter out results with status not in this set.
             limit (int): limit the number of subscriptions in the
                 results. When set to 0, no maximum is applied.
+            created (str): filter by created time or interval.
+            updated (str): filter by updated time or interval.
+            completed (str): filter by completed time or interval.
+            user_id (str or int): filter by user ID. Only available to organization admins.
+                Accepts "all" or a specific user ID.
+
+        Datetime args (created, updated, completed) can either be a
+        date-time or an interval, open or closed. Date and time expressions adhere
+        to RFC 3339. Open intervals are expressed using double-dots.
+
+        Examples:
+            * A date-time: "2018-02-12T23:20:50Z"
+            * A closed interval: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z"
+            * Open intervals: "2018-02-12T00:00:00Z/.." or "../2018-03-18T12:31:12Z"
 
         Yields:
             dict: description of a subscription results.
@@ -545,13 +563,22 @@ async def get_results(self,
             ClientError: on a client error.
         """
 
-        # TODO from old doc string, which breaks strict document checking:
-        #    Add Parameters created, updated, completed, user_id
         class _ResultsPager(Paged):
             """Navigates pages of messages about subscription results."""
             ITEMS_KEY = 'results'
 
-        params = {'status': [val for val in status or {}]}
+        params: Dict[str, Any] = {}
+        if status is not None:
+            params['status'] = [val for val in status]
+        if created is not None:
+            params['created'] = created
+        if updated is not None:
+            params['updated'] = updated
+        if completed is not None:
+            params['completed'] = completed
+        if user_id is not None:
+            params['user_id'] = user_id
+
         url = f'{self._base_url}/{subscription_id}/results'
 
         try:
@@ -570,20 +597,37 @@ class _ResultsPager(Paged):
             raise
 
     async def get_results_csv(
-        self,
-        subscription_id: str,
-        status: Optional[Sequence[Literal["created",
-                                          "queued",
-                                          "processing",
-                                          "failed",
-                                          "success"]]] = None
-    ) -> AsyncIterator[str]:
+            self,
+            subscription_id: str,
+            status: Optional[Sequence[Literal["created",
+                                              "queued",
+                                              "processing",
+                                              "failed",
+                                              "success"]]] = None,
+            created: Optional[str] = None,
+            updated: Optional[str] = None,
+            completed: Optional[str] = None,
+            user_id: Optional[Union[str, int]] = None) -> AsyncIterator[str]:
         """Iterate over rows of results CSV for a Subscription.
 
         Parameters:
             subscription_id (str): id of a subscription.
             status (Set[str]): pass result with status in this set,
                 filter out results with status not in this set.
+            created (str): filter by created time or interval.
+            updated (str): filter by updated time or interval.
+            completed (str): filter by completed time or interval.
+            user_id (str or int): filter by user ID. Only available to organization admins.
+                Accepts "all" or a specific user ID.
+
+        Datetime args (created, updated, completed) can either be a
+        date-time or an interval, open or closed. Date and time expressions adhere
+        to RFC 3339. Open intervals are expressed using double-dots.
+
+        Examples:
+            * A date-time: "2018-02-12T23:20:50Z"
+            * A closed interval: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z"
+            * Open intervals: "2018-02-12T00:00:00Z/.." or "../2018-03-18T12:31:12Z"
 
         Yields:
             str: a row from a CSV file.
@@ -592,10 +636,18 @@ async def get_results_csv(
             APIError: on an API server error.
             ClientError: on a client error.
         """
-        # TODO from old doc string, which breaks strict document checking:
-        #    Add Parameters created, updated, completed, user_id
         url = f'{self._base_url}/{subscription_id}/results'
-        params = {'status': [val for val in status or {}], 'format': 'csv'}
+        params: Dict[str, Any] = {'format': 'csv'}
+        if status is not None:
+            params['status'] = [val for val in status]
+        if created is not None:
+            params['created'] = created
+        if updated is not None:
+            params['updated'] = updated
+        if completed is not None:
+            params['completed'] = completed
+        if user_id is not None:
+            params['user_id'] = user_id
 
         # Note: retries are not implemented yet. This project has
         # retry logic for HTTP requests, but does not handle errors

planet/sync/subscriptions.py

@@ -338,6 +338,10 @@ def get_results(
                                           "failed",
                                           "success"]]] = None,
         limit: int = 100,
+        created: Optional[str] = None,
+        updated: Optional[str] = None,
+        completed: Optional[str] = None,
+        user_id: Optional[Union[str, int]] = None
     ) -> Iterator[Union[Dict[str, Any], str]]:
         """Iterate over results of a Subscription.
 
@@ -352,7 +356,20 @@ def get_results(
                 filter out results with status not in this set.
             limit (int): limit the number of subscriptions in the
                 results. When set to 0, no maximum is applied.
-            TODO: created, updated, completed, user_id
+            created (str): filter by created time or interval.
+            updated (str): filter by updated time or interval.
+            completed (str): filter by completed time or interval.
+            user_id (str or int): filter by user ID. Only available to organization admins.
+                Accepts "all" or a specific user ID.
+
+        Datetime args (created, updated, completed) can either be a
+        date-time or an interval, open or closed. Date and time expressions adhere
+        to RFC 3339. Open intervals are expressed using double-dots.
+
+        Examples:
+            * A date-time: "2018-02-12T23:20:50Z"
+            * A closed interval: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z"
+            * Open intervals: "2018-02-12T00:00:00Z/.." or "../2018-03-18T12:31:12Z"
 
         Yields:
             dict: description of a subscription results.
@@ -362,24 +379,46 @@ def get_results(
             ClientError: on a client error.
         """
         return self._client._aiter_to_iter(
-            self._client.get_results(subscription_id, status, limit))
+            self._client.get_results(subscription_id,
+                                     status,
+                                     limit,
+                                     created,
+                                     updated,
+                                     completed,
+                                     user_id))
 
     def get_results_csv(
-        self,
-        subscription_id: str,
-        status: Optional[Sequence[Literal["created",
-                                          "queued",
-                                          "processing",
-                                          "failed",
-                                          "success"]]] = None
-    ) -> Iterator[str]:
+            self,
+            subscription_id: str,
+            status: Optional[Sequence[Literal["created",
+                                              "queued",
+                                              "processing",
+                                              "failed",
+                                              "success"]]] = None,
+            created: Optional[str] = None,
+            updated: Optional[str] = None,
+            completed: Optional[str] = None,
+            user_id: Optional[Union[str, int]] = None) -> Iterator[str]:
         """Iterate over rows of results CSV for a Subscription.
 
         Parameters:
             subscription_id (str): id of a subscription.
             status (Set[str]): pass result with status in this set,
                 filter out results with status not in this set.
-            TODO: created, updated, completed, user_id
+            created (str): filter by created time or interval.
+            updated (str): filter by updated time or interval.
+            completed (str): filter by completed time or interval.
+            user_id (str or int): filter by user ID. Only available to organization admins.
+                Accepts "all" or a specific user ID.
+
+        Datetime args (created, updated, completed) can either be a
+        date-time or an interval, open or closed. Date and time expressions adhere
+        to RFC 3339. Open intervals are expressed using double-dots.
+
+        Examples:
+            * A date-time: "2018-02-12T23:20:50Z"
+            * A closed interval: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z"
+            * Open intervals: "2018-02-12T00:00:00Z/.." or "../2018-03-18T12:31:12Z"
 
         Yields:
             str: a row from a CSV file.
@@ -394,7 +433,12 @@ def get_results_csv(
         # for this entire method a la stamina:
         # https://github.com/hynek/stamina.
         return self._client._aiter_to_iter(
-            self._client.get_results_csv(subscription_id, status))
+            self._client.get_results_csv(subscription_id,
+                                         status,
+                                         created,
+                                         updated,
+                                         completed,
+                                         user_id))
 
     def get_summary(self) -> Dict[str, Any]:
         """Summarize the status of all subscriptions via GET.