runs.list filtering for queue and machine

Author: matt-aitken

.changeset/two-eagles-report.md

@@ -0,0 +1,5 @@
+---
+"@trigger.dev/sdk": patch
+---
+
+Added runs.list filtering for queue and machine

apps/webapp/app/presenters/v3/ApiRunListPresenter.server.ts

@@ -1,4 +1,10 @@
-import { parsePacket, RunStatus } from "@trigger.dev/core/v3";
+import {
+  type ListRunResponse,
+  type ListRunResponseItem,
+  MachinePresetName,
+  parsePacket,
+  RunStatus,
+} from "@trigger.dev/core/v3";
 import { type Project, type RuntimeEnvironment, type TaskRunStatus } from "@trigger.dev/database";
 import assertNever from "assert-never";
 import { z } from "zod";
@@ -104,6 +110,34 @@ export const ApiRunListSearchParams = z.object({
   "filter[createdAt][to]": CoercedDate,
   "filter[createdAt][period]": z.string().optional(),
   "filter[batch]": z.string().optional(),
+  "filter[queue]": z
+    .string()
+    .optional()
+    .transform((value) => {
+      return value ? value.split(",") : undefined;
+    }),
+  "filter[machine]": z
+    .string()
+    .optional()
+    .transform((value, ctx) => {
+      const values = value ? value.split(",") : undefined;
+      if (!values) {
+        return undefined;
+      }
+
+      const parsedValues = values.map((v) => MachinePresetName.safeParse(v));
+      const invalidValues = parsedValues.filter((result) => !result.success);
+      if (invalidValues.length > 0) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `Invalid machine values: ${invalidValues.join(", ")}`,
+        });
+
+        return z.NEVER;
+      }
+
+      return parsedValues.map((result) => result.data).filter(Boolean);
+    }),
 });
 
 type ApiRunListSearchParams = z.infer<typeof ApiRunListSearchParams>;

packages/core/src/v3/apiClient/index.ts

@@ -21,6 +21,7 @@ import {
   ListRunResponseItem,
   ListScheduleOptions,
   QueueItem,
+  QueueTypeName,
   ReplayRunResponse,
   RescheduleRunRequestBody,
   RetrieveBatchV2Response,
@@ -1147,11 +1148,35 @@ function createSearchQueryForListRuns(query?: ListRunsQueryParams): URLSearchPar
     if (query.batch) {
       searchParams.append("filter[batch]", query.batch);
     }
+
+    if (query.queue) {
+      searchParams.append(
+        "filter[queue]",
+        Array.isArray(query.queue)
+          ? query.queue.map((q) => queueNameFromQueueTypeName(q)).join(",")
+          : queueNameFromQueueTypeName(query.queue)
+      );
+    }
+
+    if (query.machine) {
+      searchParams.append(
+        "filter[machine]",
+        Array.isArray(query.machine) ? query.machine.join(",") : query.machine
+      );
+    }
   }
 
   return searchParams;
 }
 
+function queueNameFromQueueTypeName(queue: QueueTypeName): string {
+  if (queue.type === "task") {
+    return `task/${queue.name}`;
+  }
+
+  return queue.name;
+}
+
 function createSearchQueryForListWaitpointTokens(
   query?: ListWaitpointTokensQueryParams
 ): URLSearchParams {

packages/core/src/v3/apiClient/types.ts

@@ -1,4 +1,9 @@
-import { RunStatus, WaitpointTokenStatus } from "../schemas/index.js";
+import {
+  MachinePresetName,
+  QueueTypeName,
+  RunStatus,
+  WaitpointTokenStatus,
+} from "../schemas/index.js";
 import { CursorPageParams } from "./pagination.js";
 
 export interface ImportEnvironmentVariablesParams {
@@ -32,6 +37,27 @@ export interface ListRunsQueryParams extends CursorPageParams {
   schedule?: string;
   isTest?: boolean;
   batch?: string;
+  /**
+   * The queue type and name, or multiple of them.
+   *
+   * @example
+   * ```ts
+   * const runs = await runs.list({
+   *   queue: { type: "task", name: "my-task-id" },
+   * });
+   *
+   * // Or multiple queues
+   * const runs = await runs.list({
+   *   queue: [
+   *     { type: "custom", name: "my-custom-queue" },
+   *     { type: "task", name: "my-task-id" },
+   *   ],
+   * });
+   * ```
+   * */
+  queue?: Array<QueueTypeName> | QueueTypeName;
+  /** The machine name, or multiple of them. */
+  machine?: Array<MachinePresetName> | MachinePresetName;
 }
 
 export interface ListProjectRunsQueryParams extends CursorPageParams, ListRunsQueryParams {

packages/core/src/v3/schemas/queues.ts

@@ -45,6 +45,17 @@ export const ListQueueOptions = z.object({
 
 export type ListQueueOptions = z.infer<typeof ListQueueOptions>;
 
+export const QueueTypeName = z.object({
+  /** "task" or "custom" */
+  type: QueueType,
+  /** The name of your queue.
+   * For "task" type it will be the task id, for "custom" it will be the name you specified.
+   * */
+  name: z.string(),
+});
+
+export type QueueTypeName = z.infer<typeof QueueTypeName>;
+
 /**
  * When retrieving a queue you can either use the queue id,
  * or the type and name.
@@ -63,16 +74,6 @@ export type ListQueueOptions = z.infer<typeof ListQueueOptions>;
  * const q3 = await queues.retrieve({ type: "custom", name: "my-custom-queue" });
  * ```
  */
-export const RetrieveQueueParam = z.union([
-  z.string(),
-  z.object({
-    /** "task" or "custom" */
-    type: QueueType,
-    /** The name of your queue.
-     * For "task" type it will be the task id, for "custom" it will be the name you specified.
-     * */
-    name: z.string(),
-  }),
-]);
+export const RetrieveQueueParam = z.union([z.string(), QueueTypeName]);
 
 export type RetrieveQueueParam = z.infer<typeof RetrieveQueueParam>;

references/hello-world/src/trigger/sdk.ts

@@ -20,6 +20,20 @@ export const sdkMethods = task({
       logger.info("failed run", { run });
     }
 
+    for await (const run of runs.list({
+      queue: { type: "task", name: "sdk-methods" },
+      limit: 5,
+    })) {
+      logger.info("sdk-methods run", { run });
+    }
+
+    for await (const run of runs.list({
+      machine: ["small-1x", "small-2x"],
+      limit: 5,
+    })) {
+      logger.info("small machine run", { run });
+    }
+
     return runs;
   },
 });