useRunDetails()

The useRunDetails() React hook will show the live status of run.

These are the docs for Trigger.dev v2 which will be deprecated on January 31st, 2025. You probably want the v3 docs.

This hook will automatically update until the run has either completed or failed.

There are a couple of ways you can get a runId to pass in:

• In the frontend you can get the runId from the useEventDetails() hook. Although if you want the first run triggered by an event, we suggest you use useEventRunDetails().
• From the backend you can get the latest runs for a Job using the client.getRuns() method. This will return an array of runs, including their ids. You can then pass an id to your frontend to display the live status.

You can get the full status of a Run from the backend using the client.getRun() method.

If you're familiar with React Query, you'll recognize the data that is returned by this hook. React Query 5 is used internally.

Parameters

runId · string | undefined · required

The run ID to get the details for.

options · Object

Show properties

subtasks · boolean · default: false

Return subtasks, which appear in a subtasks array on every task.

cursor · string

You can use this to get more tasks, if there are more than are returned in a single batch.

take · number · default: 20

How many tasks you want to return in one go, max 50.

refreshIntervalMs · number · default: 1000

How often you want to refresh, the default is 1000. Min is 500

Returns

data · object | undefined

The data returned from the server.

Hide properties

id · string | undefined

The id of the run

status · RunStatus | undefined

The status of the run. Can be one of the following: PENDING, CANCELED, SUCCESS, QUEUED, WAITING_ON_CONNECTIONS, PREPROCESSING, STARTED, FAILURE, TIMED_OUT, ABORTED

startedAt · Date | undefined

The time the run started

completedAt · Date | undefined

The time the run completed

output · any

Whatever you returned from your run function, can be undefined

tasks · Task[]

The tasks from the run

Show Task

id · string

The Task id

displayKey · string | null

The key that you defined when creating the Task, the first param in any task.

status · TaskStatus

The Task status, can be one of PENDING, WAITING, RUNNING, COMPLETED, ERRORED, CANCELED.

name · string

The name of the Task

icon · string | null

The icon of the Task, a string. For integrations, this will be a lowercase name of the company. Can be used with the @trigger.dev/companyicons package to display an svg.

startedAt · Date | null

When the task started

completedAt · Date | null

When the task completed

nextCursor · string

If there are more tasks, you can use this to get them

error · Error | undefined

The error object if the request failed.

status · pending | success | error

The status of the request. This can be one of the following values: pending, success and error.

isLoading · boolean

true if the request is currently pending or if it is in a refetch state.

isSuccess · boolean

true if the request succeeded.

isError · boolean

true if the request failed.

isPending · boolean

true if the request is currently pending.

isLoadingError · boolean

true if the request failed with a loading error.

isRefetchError · boolean

true if the request failed with a refetch error.

components/EventDetails.tsx

"use client";

import { useRunDetails } from "@trigger.dev/react";

export function EventDetails({ runId }: { runId: string }) {
  const { isLoading, isError, data, error } = useRunDetails(runId);

  if (isLoading) {
    return <div>Loading...</div>;
  }

  if (isError) {
    return <div>Error: {error.message}</div>;
  }

  //show the run status and all the tasks
  return (
    <div>
      <h2>Run status: {data?.status}</h2>
      <div>
        {data?.tasks?.map((task) => (
          <div className="flex gap-2 items-center">
            {task.status === "ERRORED"
              ? "⛔️"
              : task.status === "COMPLETED"
              ? "✅"
              : "⏳"}
            <div className="flex gap-1.5 items-center">
              <h4 className="text-base">{task.displayKey ?? task.name}</h4>
            </div>
          </div>
        ))}
      </div>
    </div>
  );
}