feat: getInvocations endpoint

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 50
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-5ee2116982adf46664acf84b8ba4b56ba65780983506c63d9b005dab49def757.yml
-openapi_spec_hash: 42a3a519301d0e2bb2b5a71018915b55
-config_hash: 0d150b61cae2dc57d3648ceae7784966
+configured_endpoints: 51
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-8b5a722e4964d2d1dcdc34afccb6d742e1c927cbbd622264c8734f132e31a0f5.yml
+openapi_spec_hash: ed101ff177c2e962653ca65acf939336
+config_hash: 49c2ff978aaa5ccb4ce324a72f116010

api.md

@@ -44,13 +44,15 @@ Types:
 - <code><a href="./src/resources/invocations.ts">InvocationCreateResponse</a></code>
 - <code><a href="./src/resources/invocations.ts">InvocationRetrieveResponse</a></code>
 - <code><a href="./src/resources/invocations.ts">InvocationUpdateResponse</a></code>
+- <code><a href="./src/resources/invocations.ts">InvocationListResponse</a></code>
 - <code><a href="./src/resources/invocations.ts">InvocationFollowResponse</a></code>
 
 Methods:
 
 - <code title="post /invocations">client.invocations.<a href="./src/resources/invocations.ts">create</a>({ ...params }) -> InvocationCreateResponse</code>
 - <code title="get /invocations/{id}">client.invocations.<a href="./src/resources/invocations.ts">retrieve</a>(id) -> InvocationRetrieveResponse</code>
 - <code title="patch /invocations/{id}">client.invocations.<a href="./src/resources/invocations.ts">update</a>(id, { ...params }) -> InvocationUpdateResponse</code>
+- <code title="get /invocations">client.invocations.<a href="./src/resources/invocations.ts">list</a>({ ...params }) -> InvocationListResponsesOffsetPagination</code>
 - <code title="delete /invocations/{id}/browsers">client.invocations.<a href="./src/resources/invocations.ts">deleteBrowsers</a>(id) -> void</code>
 - <code title="get /invocations/{id}/events">client.invocations.<a href="./src/resources/invocations.ts">follow</a>(id, { ...params }) -> InvocationFollowResponse</code>
 

src/client.ts

@@ -37,6 +37,9 @@ import {
   InvocationCreateResponse,
   InvocationFollowParams,
   InvocationFollowResponse,
+  InvocationListParams,
+  InvocationListResponse,
+  InvocationListResponsesOffsetPagination,
   InvocationRetrieveResponse,
   InvocationStateEvent,
   InvocationUpdateParams,
@@ -868,9 +871,12 @@ export declare namespace Kernel {
     type InvocationCreateResponse as InvocationCreateResponse,
     type InvocationRetrieveResponse as InvocationRetrieveResponse,
     type InvocationUpdateResponse as InvocationUpdateResponse,
+    type InvocationListResponse as InvocationListResponse,
     type InvocationFollowResponse as InvocationFollowResponse,
+    type InvocationListResponsesOffsetPagination as InvocationListResponsesOffsetPagination,
     type InvocationCreateParams as InvocationCreateParams,
     type InvocationUpdateParams as InvocationUpdateParams,
+    type InvocationListParams as InvocationListParams,
     type InvocationFollowParams as InvocationFollowParams,
   };
 

src/resources/index.ts

@@ -30,10 +30,13 @@ export {
   type InvocationCreateResponse,
   type InvocationRetrieveResponse,
   type InvocationUpdateResponse,
+  type InvocationListResponse,
   type InvocationFollowResponse,
   type InvocationCreateParams,
   type InvocationUpdateParams,
+  type InvocationListParams,
   type InvocationFollowParams,
+  type InvocationListResponsesOffsetPagination,
 } from './invocations';
 export { Profiles, type ProfileListResponse, type ProfileCreateParams } from './profiles';
 export {

src/resources/invocations.ts

@@ -3,6 +3,7 @@
 import { APIResource } from '../core/resource';
 import * as Shared from './shared';
 import { APIPromise } from '../core/api-promise';
+import { OffsetPagination, type OffsetPaginationParams, PagePromise } from '../core/pagination';
 import { Stream } from '../core/streaming';
 import { buildHeaders } from '../internal/headers';
 import { RequestOptions } from '../internal/request-options';
@@ -58,6 +59,28 @@ export class Invocations extends APIResource {
     return this._client.patch(path`/invocations/${id}`, { body, ...options });
   }
 
+  /**
+   * List invocations. Optionally filter by application name, action name, status,
+   * deployment ID, or start time.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const invocationListResponse of client.invocations.list()) {
+   *   // ...
+   * }
+   * ```
+   */
+  list(
+    query: InvocationListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<InvocationListResponsesOffsetPagination, InvocationListResponse> {
+    return this._client.getAPIList('/invocations', OffsetPagination<InvocationListResponse>, {
+      query,
+      ...options,
+    });
+  }
+
   /**
    * Delete all browser sessions created within the specified invocation.
    *
@@ -97,6 +120,8 @@ export class Invocations extends APIResource {
   }
 }
 
+export type InvocationListResponsesOffsetPagination = OffsetPagination<InvocationListResponse>;
+
 /**
  * An event representing the current state of an invocation.
  */
@@ -291,6 +316,55 @@ export interface InvocationUpdateResponse {
   status_reason?: string;
 }
 
+export interface InvocationListResponse {
+  /**
+   * ID of the invocation
+   */
+  id: string;
+
+  /**
+   * Name of the action invoked
+   */
+  action_name: string;
+
+  /**
+   * Name of the application
+   */
+  app_name: string;
+
+  /**
+   * RFC 3339 Nanoseconds timestamp when the invocation started
+   */
+  started_at: string;
+
+  /**
+   * Status of the invocation
+   */
+  status: 'queued' | 'running' | 'succeeded' | 'failed';
+
+  /**
+   * RFC 3339 Nanoseconds timestamp when the invocation finished (null if still
+   * running)
+   */
+  finished_at?: string | null;
+
+  /**
+   * Output produced by the action, rendered as a JSON string. This could be: string,
+   * number, boolean, array, object, or null.
+   */
+  output?: string;
+
+  /**
+   * Payload provided to the invocation. This is a string that can be parsed as JSON.
+   */
+  payload?: string;
+
+  /**
+   * Status reason
+   */
+  status_reason?: string;
+}
+
 /**
  * Union type representing any invocation event.
  */
@@ -340,6 +414,34 @@ export interface InvocationUpdateParams {
   output?: string;
 }
 
+export interface InvocationListParams extends OffsetPaginationParams {
+  /**
+   * Filter results by action name.
+   */
+  action_name?: string;
+
+  /**
+   * Filter results by application name.
+   */
+  app_name?: string;
+
+  /**
+   * Filter results by deployment ID.
+   */
+  deployment_id?: string;
+
+  /**
+   * Show invocations that have started since the given time (RFC timestamps or
+   * durations like 5m).
+   */
+  since?: string;
+
+  /**
+   * Filter results by invocation status.
+   */
+  status?: 'queued' | 'running' | 'succeeded' | 'failed';
+}
+
 export interface InvocationFollowParams {
   /**
    * Show logs since the given time (RFC timestamps or durations like 5m).
@@ -353,9 +455,12 @@ export declare namespace Invocations {
     type InvocationCreateResponse as InvocationCreateResponse,
     type InvocationRetrieveResponse as InvocationRetrieveResponse,
     type InvocationUpdateResponse as InvocationUpdateResponse,
+    type InvocationListResponse as InvocationListResponse,
     type InvocationFollowResponse as InvocationFollowResponse,
+    type InvocationListResponsesOffsetPagination as InvocationListResponsesOffsetPagination,
     type InvocationCreateParams as InvocationCreateParams,
     type InvocationUpdateParams as InvocationUpdateParams,
+    type InvocationListParams as InvocationListParams,
     type InvocationFollowParams as InvocationFollowParams,
   };
 }

tests/api-resources/invocations.test.ts

@@ -64,6 +64,37 @@ describe('resource invocations', () => {
     const response = await client.invocations.update('id', { status: 'succeeded', output: 'output' });
   });
 
+  // Prism tests are disabled
+  test.skip('list', async () => {
+    const responsePromise = client.invocations.list();
+    const rawResponse = await responsePromise.asResponse();
+    expect(rawResponse).toBeInstanceOf(Response);
+    const response = await responsePromise;
+    expect(response).not.toBeInstanceOf(Response);
+    const dataAndResponse = await responsePromise.withResponse();
+    expect(dataAndResponse.data).toBe(response);
+    expect(dataAndResponse.response).toBe(rawResponse);
+  });
+
+  // Prism tests are disabled
+  test.skip('list: request options and params are passed correctly', async () => {
+    // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error
+    await expect(
+      client.invocations.list(
+        {
+          action_name: 'action_name',
+          app_name: 'app_name',
+          deployment_id: 'deployment_id',
+          limit: 1,
+          offset: 0,
+          since: '2025-06-20T12:00:00Z',
+          status: 'queued',
+        },
+        { path: '/_stainless_unknown_path' },
+      ),
+    ).rejects.toThrow(Kernel.NotFoundError);
+  });
+
   // Prism tests are disabled
   test.skip('deleteBrowsers', async () => {
     const responsePromise = client.invocations.deleteBrowsers('id');