chore(closes OPEN-8647): add endpoint to retrieve aggregated user data for inference pipelines

Author: stainless-app[bot]

.stats.yml

@@ -1,3 +1,3 @@
-configured_endpoints: 26
-openapi_spec_hash: 6f6cb98b7755d18274dd51e857508336
-config_hash: cc9a32249c08143687799eb8de187d6a
+configured_endpoints: 27
+openapi_spec_hash: c70c3eccfe803e99c14e97e650b1e314
+config_hash: 1f7626e569e1a74574a58d7883170a0e

MIGRATION.md

@@ -78,6 +78,7 @@ This affects the following methods:
 - `client.commits.testResults.list()`
 - `client.inferencePipelines.retrieve()`
 - `client.inferencePipelines.update()`
+- `client.inferencePipelines.retrieveUsers()`
 - `client.inferencePipelines.testResults.list()`
 - `client.tests.listResults()`
 

api.md

@@ -109,12 +109,14 @@ Types:
 
 - <code><a href="./src/resources/inference-pipelines/inference-pipelines.ts">InferencePipelineRetrieveResponse</a></code>
 - <code><a href="./src/resources/inference-pipelines/inference-pipelines.ts">InferencePipelineUpdateResponse</a></code>
+- <code><a href="./src/resources/inference-pipelines/inference-pipelines.ts">InferencePipelineRetrieveUsersResponse</a></code>
 
 Methods:
 
 - <code title="get /inference-pipelines/{inferencePipelineId}">client.inferencePipelines.<a href="./src/resources/inference-pipelines/inference-pipelines.ts">retrieve</a>(inferencePipelineID, { ...params }) -> InferencePipelineRetrieveResponse</code>
 - <code title="put /inference-pipelines/{inferencePipelineId}">client.inferencePipelines.<a href="./src/resources/inference-pipelines/inference-pipelines.ts">update</a>(inferencePipelineID, { ...params }) -> InferencePipelineUpdateResponse</code>
 - <code title="delete /inference-pipelines/{inferencePipelineId}">client.inferencePipelines.<a href="./src/resources/inference-pipelines/inference-pipelines.ts">delete</a>(inferencePipelineID) -> void</code>
+- <code title="get /inference-pipelines/{inferencePipelineId}/users">client.inferencePipelines.<a href="./src/resources/inference-pipelines/inference-pipelines.ts">retrieveUsers</a>(inferencePipelineID, { ...params }) -> InferencePipelineRetrieveUsersResponse</code>
 
 ## Data
 

src/client.ts

@@ -28,6 +28,8 @@ import { CommitRetrieveResponse, Commits } from './resources/commits/commits';
 import {
   InferencePipelineRetrieveParams,
   InferencePipelineRetrieveResponse,
+  InferencePipelineRetrieveUsersParams,
+  InferencePipelineRetrieveUsersResponse,
   InferencePipelineUpdateParams,
   InferencePipelineUpdateResponse,
   InferencePipelines,
@@ -779,8 +781,10 @@ export declare namespace Openlayer {
     InferencePipelines as InferencePipelines,
     type InferencePipelineRetrieveResponse as InferencePipelineRetrieveResponse,
     type InferencePipelineUpdateResponse as InferencePipelineUpdateResponse,
+    type InferencePipelineRetrieveUsersResponse as InferencePipelineRetrieveUsersResponse,
     type InferencePipelineRetrieveParams as InferencePipelineRetrieveParams,
     type InferencePipelineUpdateParams as InferencePipelineUpdateParams,
+    type InferencePipelineRetrieveUsersParams as InferencePipelineRetrieveUsersParams,
   };
 
   export { Storage as Storage };

src/resources/index.ts

@@ -5,8 +5,10 @@ export {
   InferencePipelines,
   type InferencePipelineRetrieveResponse,
   type InferencePipelineUpdateResponse,
+  type InferencePipelineRetrieveUsersResponse,
   type InferencePipelineRetrieveParams,
   type InferencePipelineUpdateParams,
+  type InferencePipelineRetrieveUsersParams,
 } from './inference-pipelines/inference-pipelines';
 export {
   Projects,

src/resources/inference-pipelines/index.ts

@@ -5,8 +5,10 @@ export {
   InferencePipelines,
   type InferencePipelineRetrieveResponse,
   type InferencePipelineUpdateResponse,
+  type InferencePipelineRetrieveUsersResponse,
   type InferencePipelineRetrieveParams,
   type InferencePipelineUpdateParams,
+  type InferencePipelineRetrieveUsersParams,
 } from './inference-pipelines';
 export { Rows, type RowUpdateResponse, type RowUpdateParams } from './rows';
 export { TestResults, type TestResultListResponse, type TestResultListParams } from './test-results';

src/resources/inference-pipelines/inference-pipelines.ts

@@ -71,6 +71,29 @@ export class InferencePipelines extends APIResource {
       headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
     });
   }
+
+  /**
+   * Get aggregated user data for an inference pipeline with pagination and metadata.
+   *
+   * Returns a list of users who have interacted with the inference pipeline,
+   * including their activity statistics such as session counts, record counts, token
+   * usage, and costs.
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.inferencePipelines.retrieveUsers(
+   *     '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+   *   );
+   * ```
+   */
+  retrieveUsers(
+    inferencePipelineID: string,
+    query: InferencePipelineRetrieveUsersParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<InferencePipelineRetrieveUsersResponse> {
+    return this._client.get(path`/inference-pipelines/${inferencePipelineID}/users`, { query, ...options });
+  }
 }
 
 export interface InferencePipelineRetrieveResponse {
@@ -809,6 +832,52 @@ export namespace InferencePipelineUpdateResponse {
   }
 }
 
+export interface InferencePipelineRetrieveUsersResponse {
+  /**
+   * Array of user aggregation data
+   */
+  items: Array<InferencePipelineRetrieveUsersResponse.Item>;
+}
+
+export namespace InferencePipelineRetrieveUsersResponse {
+  export interface Item {
+    /**
+     * The unique user identifier
+     */
+    id: string;
+
+    /**
+     * Total cost for this user
+     */
+    cost: number;
+
+    /**
+     * Timestamp of the user's first event/trace
+     */
+    dateOfFirstRecord: string;
+
+    /**
+     * Timestamp of the user's last event/trace
+     */
+    dateOfLastRecord: string;
+
+    /**
+     * Total number of traces/rows for this user
+     */
+    records: number;
+
+    /**
+     * Count of unique sessions for this user
+     */
+    sessions: number;
+
+    /**
+     * Total token count for this user
+     */
+    tokens: number;
+  }
+}
+
 export interface InferencePipelineRetrieveParams {
   /**
    * Expand specific nested objects.
@@ -834,6 +903,18 @@ export interface InferencePipelineUpdateParams {
   referenceDatasetUri?: string | null;
 }
 
+export interface InferencePipelineRetrieveUsersParams {
+  /**
+   * The page to return in a paginated query.
+   */
+  page?: number;
+
+  /**
+   * Maximum number of items to return per page.
+   */
+  perPage?: number;
+}
+
 InferencePipelines.Data = Data;
 InferencePipelines.Rows = Rows;
 InferencePipelines.TestResults = TestResults;
@@ -842,8 +923,10 @@ export declare namespace InferencePipelines {
   export {
     type InferencePipelineRetrieveResponse as InferencePipelineRetrieveResponse,
     type InferencePipelineUpdateResponse as InferencePipelineUpdateResponse,
+    type InferencePipelineRetrieveUsersResponse as InferencePipelineRetrieveUsersResponse,
     type InferencePipelineRetrieveParams as InferencePipelineRetrieveParams,
     type InferencePipelineUpdateParams as InferencePipelineUpdateParams,
+    type InferencePipelineRetrieveUsersParams as InferencePipelineRetrieveUsersParams,
   };
 
   export {

tests/api-resources/inference-pipelines/inference-pipelines.test.ts

@@ -66,4 +66,26 @@ describe('resource inferencePipelines', () => {
     expect(dataAndResponse.data).toBe(response);
     expect(dataAndResponse.response).toBe(rawResponse);
   });
+
+  test('retrieveUsers', async () => {
+    const responsePromise = client.inferencePipelines.retrieveUsers('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');
+    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);
+  });
+
+  test('retrieveUsers: 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.inferencePipelines.retrieveUsers(
+        '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+        { page: 1, perPage: 1 },
+        { path: '/_stainless_unknown_path' },
+      ),
+    ).rejects.toThrow(Openlayer.NotFoundError);
+  });
 });