epilot-dev · Seejey01 · Aug 5, 2026
diff --git a/.changeset/automation-client-search-executions.md b/.changeset/automation-client-search-executions.md
@@ -0,0 +1,5 @@
+---
+"@epilot/automation-client": minor
+---
+
+Add `searchExecutions` operation (`POST /v1/automation/executions:search`) — cursor-based pagination for an entity's automation executions (`size`, `cursor` body params, `next_cursor` in the response)
diff --git a/clients/automation-client/package.json b/clients/automation-client/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@epilot/automation-client",
-  "version": "2.33.4",
+  "version": "2.34.0",
   "description": "Client library for epilot automation API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

diff --git a/clients/automation-client/src/openapi-runtime.json b/clients/automation-client/src/openapi-runtime.json
@@ -130,6 +130,18 @@
         "responses": {}
       }
     },
+    "/v1/automation/executions:search": {
+      "post": {
+        "operationId": "searchExecutions",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {}
+          }
+        },
+        "responses": {}
+      }
+    },
     "/v1/automation/executions/bulk-jobs": {
       "post": {
         "operationId": "bulkTriggerExecutions",

diff --git a/clients/automation-client/src/openapi.d.ts b/clients/automation-client/src/openapi.d.ts
@@ -720,9 +720,64 @@ declare namespace Components {
              */
             remove?: string[];
             /**
-             * Assignees to add to the thread
+             * Assignees to add to the thread. For even_distribution this may contain group IDs (prefixed "group_") whose members are candidates.
              */
             add?: string[];
+            /**
+             * How assignees in `add` are resolved.
+             * - direct: assign exactly the users in `add` (default).
+             * - even_distribution: treat `add` as a candidate pool (users and/or groups)
+             *   and assign the least-loaded available agent.
+             * - sequential: reserved for future use.
+             *
+             */
+            assignment_type?: "direct" | "even_distribution" | "sequential";
+            /**
+             * Candidate condition for even_distribution: when true, skip users who
+             * are currently absent (out-of-office). Opt-in; defaults to false.
+             *
+             */
+            only_available_users?: boolean;
+            /**
+             * Candidate condition for even_distribution: when true, only assign to
+             * users whose skills (tags) match a label on the message. Opt-in;
+             * defaults to false.
+             *
+             */
+            match_user_skills?: boolean;
+            /**
+             * Candidate condition (with match_user_skills): label families
+             * (taxonomy slugs) that must match. A user qualifies only if it shares
+             * a label with the message within each of these categories. Leave empty
+             * to match on any label (flat OR across all categories).
+             *
+             */
+            required_skill_categories?: string[];
+            /**
+             * How strictly required skill categories are matched (applies with
+             * match_user_skills and required skill categories set).
+             * - require_all: hard match (default) — a user must match every required
+             *   category the message has a label in.
+             * - prefer: soft match — prefer the best-matching users, relaxing to
+             *   fewer categories only when no better match exists; a user matching
+             *   no category is never eligible (the fallback then applies).
+             *
+             */
+            skill_match_mode?: "require_all" | "prefer";
+            /**
+             * What to do when smart assignment resolves no assignable candidate.
+             * Applies to even_distribution.
+             * - leave_unassigned: leave the thread unassigned (default).
+             * - assign_to_fallback: route to the users/groups in `fallback_assignees`.
+             *
+             */
+            fallback?: "leave_unassigned" | "assign_to_fallback";
+            /**
+             * Target user/group IDs (group IDs prefixed "group_") to assign when
+             * `fallback` is "assign_to_fallback".
+             *
+             */
+            fallback_assignees?: string[];
         }
         /**
          * example:
@@ -3596,6 +3651,40 @@ declare namespace Components {
             total: number;
             results: AutomationFlow[];
         }
+        export interface SearchExecutionsReq {
+            entity_id: /**
+             * example:
+             * e3d3ebac-baab-4395-abf4-50b5bf1f8b74
+             */
+            EntityId;
+            /**
+             * Include flow automations in the response
+             */
+            include_flows?: boolean;
+            /**
+             * Max number of executions to return per page
+             */
+            size?: number;
+            /**
+             * Opaque cursor returned as next_cursor by a previous page.
+             * Pass it to fetch the next page of results.
+             *
+             */
+            cursor?: string;
+        }
+        export interface SearchExecutionsResp {
+            /**
+             * Number of executions in this page
+             */
+            total: number;
+            results: AutomationExecution[];
+            /**
+             * Opaque cursor to fetch the next page of results.
+             * Only present when more results are available.
+             *
+             */
+            next_cursor?: string;
+        }
         export interface SendEmailAction {
             id?: /**
              * example:
@@ -5046,6 +5135,20 @@ declare namespace Paths {
             Components.Responses.NotFoundError;
         }
     }
+    namespace SearchExecutions {
+        export type RequestBody = Components.Schemas.SearchExecutionsReq;
+        namespace Responses {
+            export type $200 = Components.Schemas.SearchExecutionsResp;
+            export type $403 = /**
+             * example:
+             * {
+             *   "status": 403,
+             *   "error": "Forbidden"
+             * }
+             */
+            Components.Responses.ForbiddenError;
+        }
+    }
     namespace SearchFlows {
         namespace Parameters {
             export type From = number;
@@ -5189,6 +5292,20 @@ export interface OperationMethods {
     data?: Paths.StartExecution.RequestBody,
     config?: AxiosRequestConfig  
   ): OperationResponse<Paths.StartExecution.Responses.$201>
+  /**
+   * searchExecutions - searchExecutions
+   * 
+   * Search automation executions of an entity with cursor-based pagination.
+   * Returns pages of up to 100 executions, newest first.
+   * Prefer this over GET /v1/automation/executions, which returns the full
+   * execution history in a single response.
+   * 
+   */
+  'searchExecutions'(
+    parameters?: Parameters<UnknownParamsObject> | null,
+    data?: Paths.SearchExecutions.RequestBody,
+    config?: AxiosRequestConfig  
+  ): OperationResponse<Paths.SearchExecutions.Responses.$200>
   /**
    * bulkTriggerExecutions - bulkTriggerExecutions
    * 
@@ -5365,6 +5482,22 @@ export interface PathsDictionary {
       config?: AxiosRequestConfig  
     ): OperationResponse<Paths.StartExecution.Responses.$201>
   }
+  ['/v1/automation/executions:search']: {
+    /**
+     * searchExecutions - searchExecutions
+     * 
+     * Search automation executions of an entity with cursor-based pagination.
+     * Returns pages of up to 100 executions, newest first.
+     * Prefer this over GET /v1/automation/executions, which returns the full
+     * execution history in a single response.
+     * 
+     */
+    'post'(
+      parameters?: Parameters<UnknownParamsObject> | null,
+      data?: Paths.SearchExecutions.RequestBody,
+      config?: AxiosRequestConfig  
+    ): OperationResponse<Paths.SearchExecutions.Responses.$200>
+  }
   ['/v1/automation/executions/bulk-jobs']: {
     /**
      * bulkTriggerExecutions - bulkTriggerExecutions
@@ -5572,6 +5705,8 @@ export type ResumeToken = Components.Schemas.ResumeToken;
 export type RetryReq = Components.Schemas.RetryReq;
 export type RetryStrategy = Components.Schemas.RetryStrategy;
 export type SearchAutomationsResp = Components.Schemas.SearchAutomationsResp;
+export type SearchExecutionsReq = Components.Schemas.SearchExecutionsReq;
+export type SearchExecutionsResp = Components.Schemas.SearchExecutionsResp;
 export type SendEmailAction = Components.Schemas.SendEmailAction;
 export type SendEmailActionConfig = Components.Schemas.SendEmailActionConfig;
 export type SendEmailCondition = Components.Schemas.SendEmailCondition;

diff --git a/clients/automation-client/src/openapi.json b/clients/automation-client/src/openapi.json
@@ -621,6 +621,42 @@
         }
       }
     },
+    "/v1/automation/executions:search": {
+      "post": {
+        "operationId": "searchExecutions",
+        "summary": "searchExecutions",
+        "description": "Search automation executions of an entity with cursor-based pagination.\nReturns pages of up to 100 executions, newest first.\nPrefer this over GET /v1/automation/executions, which returns the full\nexecution history in a single response.\n",
+        "tags": [
+          "executions"
+        ],
+        "requestBody": {
+          "description": "Search parameters",
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SearchExecutionsReq"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "A page of automation executions",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SearchExecutionsResp"
+                }
+              }
+            }
+          },
+          "403": {
+            "$ref": "#/components/responses/ForbiddenError"
+          }
+        }
+      }
+    },
     "/v1/automation/executions/bulk-jobs": {
       "post": {
         "operationId": "bulkTriggerExecutions",
@@ -2187,7 +2223,59 @@
           },
           "add": {
             "type": "array",
-            "description": "Assignees to add to the thread",
+            "description": "Assignees to add to the thread. For even_distribution this may contain group IDs (prefixed \"group_\") whose members are candidates.",
+            "items": {
+              "type": "string"
+            }
+          },
+          "assignment_type": {
+            "type": "string",
+            "description": "How assignees in `add` are resolved.\n- direct: assign exactly the users in `add` (default).\n- even_distribution: treat `add` as a candidate pool (users and/or groups)\n  and assign the least-loaded available agent.\n- sequential: reserved for future use.\n",
+            "enum": [
+              "direct",
+              "even_distribution",
+              "sequential"
+            ],
+            "default": "direct"
+          },
+          "only_available_users": {
+            "type": "boolean",
+            "description": "Candidate condition for even_distribution: when true, skip users who\nare currently absent (out-of-office). Opt-in; defaults to false.\n",
+            "default": false
+          },
+          "match_user_skills": {
+            "type": "boolean",
+            "description": "Candidate condition for even_distribution: when true, only assign to\nusers whose skills (tags) match a label on the message. Opt-in;\ndefaults to false.\n",
+            "default": false
+          },
+          "required_skill_categories": {
+            "type": "array",
+            "description": "Candidate condition (with match_user_skills): label families\n(taxonomy slugs) that must match. A user qualifies only if it shares\na label with the message within each of these categories. Leave empty\nto match on any label (flat OR across all categories).\n",
+            "items": {
+              "type": "string"
+            }
+          },
+          "skill_match_mode": {
+            "type": "string",
+            "description": "How strictly required skill categories are matched (applies with\nmatch_user_skills and required skill categories set).\n- require_all: hard match (default) — a user must match every required\n  category the message has a label in.\n- prefer: soft match — prefer the best-matching users, relaxing to\n  fewer categories only when no better match exists; a user matching\n  no category is never eligible (the fallback then applies).\n",
+            "enum": [
+              "require_all",
+              "prefer"
+            ],
+            "default": "require_all"
+          },
+          "fallback": {
+            "type": "string",
+            "description": "What to do when smart assignment resolves no assignable candidate.\nApplies to even_distribution.\n- leave_unassigned: leave the thread unassigned (default).\n- assign_to_fallback: route to the users/groups in `fallback_assignees`.\n",
+            "enum": [
+              "leave_unassigned",
+              "assign_to_fallback"
+            ],
+            "default": "leave_unassigned"
+          },
+          "fallback_assignees": {
+            "type": "array",
+            "description": "Target user/group IDs (group IDs prefixed \"group_\") to assign when\n`fallback` is \"assign_to_fallback\".\n",
             "items": {
               "type": "string"
             }
@@ -3885,6 +3973,56 @@
           "results"
         ]
       },
+      "SearchExecutionsReq": {
+        "type": "object",
+        "properties": {
+          "entity_id": {
+            "$ref": "#/components/schemas/EntityId"
+          },
+          "include_flows": {
+            "description": "Include flow automations in the response",
+            "type": "boolean",
+            "default": false
+          },
+          "size": {
+            "description": "Max number of executions to return per page",
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 100,
+            "default": 25
+          },
+          "cursor": {
+            "description": "Opaque cursor returned as next_cursor by a previous page.\nPass it to fetch the next page of results.\n",
+            "type": "string"
+          }
+        },
+        "required": [
+          "entity_id"
+        ]
+      },
+      "SearchExecutionsResp": {
+        "type": "object",
+        "properties": {
+          "total": {
+            "description": "Number of executions in this page",
+            "type": "number"
+          },
+          "results": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/AutomationExecution"
+            }
+          },
+          "next_cursor": {
+            "description": "Opaque cursor to fetch the next page of results.\nOnly present when more results are available.\n",
+            "type": "string"
+          }
+        },
+        "required": [
+          "total",
+          "results"
+        ]
+      },
       "StartExecutionRequest": {
         "type": "object",
         "properties": {