RecoupGet a Free AuditFree Audit

API REFERENCE

Get Tasks

On this page
GET/api/tasks

Retrieve scheduled tasks. Each task includes recent_runs (last 5 runs), upcoming (next scheduled run times) sourced directly from the Trigger.dev API, and owner_email when an account email exists for the task owner. Supports filtering by id, account_id, or artist_account_id.

Authentication

x-api-key in header

bearerAuth bearer

Request

cURL
curl --request GET \
  --url 'https://api.recoupable.dev/api/tasks' \
  --header 'x-api-key: YOUR_API_KEY'

Replace the YOUR_ placeholders with your values. Required query parameters are included; optional parameters are listed below.

Parameters

Query parameters

idstring

Filter by task ID (UUID). Returns a single task matching the provided ID. Admin callers may retrieve any task by ID regardless of owner; non-admin callers only receive the task if it belongs to their authenticated account.

account_idstring

Filter tasks to only include those for the specified account.

artist_account_idstring

Filter tasks to only include those for the specified artist account.

Responses

200Tasks retrieved successfully

application/json

statusstring · enumrequired

Status of the request

Values: "success", "error"

tasksarray<Task>required

Array of task objects

Item properties for tasks
idstring

Unique identifier for the task

format: uuid

titlestring

Descriptive title or name of the task

promptstring

Detailed instruction or prompt for task execution

schedulestring

Cron expression defining when the task should execute (e.g., '0 10 * * *')

timezonestringnullable

IANA time zone the task's cron is interpreted in, read from the Trigger.dev schedule (the source of truth). Null when the task has no schedule or the timezone can't be read.

account_idstring

Unique identifier for the associated account

format: uuid

artist_account_idstring

Unique identifier for the associated artist account

format: uuid

enabledbooleannullable

Whether the task is enabled. Defaults to true.

trigger_schedule_idstringnullable

Identifier for the trigger schedule associated with this task

recent_runsarray<TaskRunResponse>

Last 5 runs for this task, sourced from the Trigger.dev API.

Item properties for recent_runs
idstringrequired

The unique run identifier, prefixed with run_

statusstring · enumrequired

Current run status

Values: "PENDING_VERSION", "DELAYED", "QUEUED", "EXECUTING", "REATTEMPTING", "FROZEN", "COMPLETED", "CANCELED", "FAILED", "CRASHED", "INTERRUPTED", "SYSTEM_FAILURE"

taskIdentifierstringrequired

The task type identifier (e.g. 'setup-sandbox', 'run-sandbox-command')

idempotencyKeystringnullable

Idempotency key used to deduplicate trigger requests

versionstring

The worker version that executed the run

isTestboolean

Whether this is a test run

createdAtstringrequired

When the run was created (ISO 8601)

format: date-time

updatedAtstringrequired

When the run was last updated (ISO 8601)

format: date-time

startedAtstringnullable

When execution started (null if not yet started)

format: date-time

finishedAtstringnullable

When the run finished (null if still running)

format: date-time

delayedUntilstringnullable

If delayed, when the run becomes eligible to execute

format: date-time

ttlanynullable

Time-to-live. If the run is not started within this duration, it expires.

expiredAtstringnullable

When the run expired (null if not expired)

format: date-time

tagsarray<string>

Tags associated with this run (max 10)

Item properties for tags

string

metadataobjectnullable

JSON metadata attached to the run

costInCentsnumber

Compute cost of the run in cents

baseCostInCentsnumber

Base invocation cost in cents

durationMsnumber

Compute duration in milliseconds

envobject

Environment the run executed in

Properties for env
idstring
namestring
userstringnullable
depthinteger

Nesting depth for child runs

batchIdstringnullable

Batch ID if triggered as part of a batch

triggerFunctionstring · enum

The function used to trigger this run

Values: "trigger", "triggerAndWait", "batchTrigger", "batchTriggerAndWait"

payloadanynullable

Input payload for the task. Only present when retrieving by runId.

outputone ofnullable

Task output data. Only present when retrieving by runId, and only populated when status is COMPLETED. Shape varies by taskIdentifier. The create-content task returns the schema below; other tasks return their own.

Properties for output
oneOf · CreateContentRunOutput 1

Output payload for a create-content task run. Returned in output when status is COMPLETED. Agents should poll /api/tasks/runs?runId=… and read these fields once the run is done.

videoSourceUrlstringrequired

URL to the rendered final 9:16 video (image + motion + audio + caption already composed).

format: uri

imageUrlstringrequired

URL to the base image used for video generation.

format: uri

captionTextstringrequired

The caption text burned into the video.

templatestringrequired

Template id used for this run (e.g. album-record-store, artist-caption-bedroom).

lipsyncboolean

Whether lipsync was applied (audio-driven mouth animation).

audioobject

Metadata about the song clip used in the final composition.

Properties for audio
songTitlestring
songFilenamestring
startSecondsnumber

Offset into the source song where the clip starts.

durationSecondsnumber

Length of the audio clip in seconds.

clipLyricsstringnullable

Lyrics for the chosen clip, when available.

clipMoodstringnullable

Inferred mood for the chosen clip, when available.

oneOf · object 2

Generic task output (for tasks not yet schema'd)

object

errorobjectnullable

Error details if the run failed. Only present when retrieving by runId.

Properties for error
messagestring

Human-readable error message

namestring

Error name or type

stackTracestring

Stack trace

attemptsarray<object>

Attempt history. Only present when retrieving by runId.

Item properties for attempts
idstring

Attempt ID, prefixed with attempt_

statusstring · enum

Values: "PENDING", "EXECUTING", "PAUSED", "COMPLETED", "FAILED", "CANCELED"

createdAtstring

format: date-time

updatedAtstring

format: date-time

startedAtstringnullable

format: date-time

completedAtstringnullable

format: date-time

errorobjectnullable
Properties for error
messagestring
namestring
stackTracestring
scheduleobjectnullable

Schedule information if triggered by a schedule. Only present when retrieving by runId.

relatedRunsobjectnullable

Related run references (root, parent, children). Only present when retrieving by runId.

upcomingarray<string>

Next scheduled run times.

Item properties for upcoming

string

owner_emailstringnullable

Primary email address for the task owner account when one exists.

artist_namestringnullable

Display name of the artist account the task runs for (artist_account_id), so a task list can label rows without a roster lookup. Null when the artist account no longer exists.

modelstringnullable

AI model identifier used when the task runs. When present as a string, must be non-empty; otherwise null if unset.

minLength: 1

errorstring

Error message (only present if status is error)

400Bad request

application/json

errorintegerrequired

format: int32

messagestringrequired
401Unauthorized - missing or invalid credentials

application/json

errorintegerrequired

format: int32

messagestringrequired
403Forbidden - account_id is outside caller authorization scope

application/json

errorintegerrequired

format: int32

messagestringrequired
500Internal server error while retrieving tasks.

application/json

errorintegerrequired

format: int32

messagestringrequired

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download releases.json
View operation source
json
{
  "description": "Retrieve scheduled tasks. Each task includes `recent_runs` (last 5 runs), `upcoming` (next scheduled run times) sourced directly from the Trigger.dev API, and `owner_email` when an account email exists for the task owner. Supports filtering by id, account_id, or artist_account_id.",
  "security": [
    {
      "apiKeyAuth": []
    },
    {
      "bearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "id",
      "in": "query",
      "description": "Filter by task ID (UUID). Returns a single task matching the provided ID. Admin callers may retrieve any task by ID regardless of owner; non-admin callers only receive the task if it belongs to their authenticated account.",
      "required": false,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "name": "account_id",
      "in": "query",
      "description": "Filter tasks to only include those for the specified account.",
      "required": false,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "name": "artist_account_id",
      "in": "query",
      "description": "Filter tasks to only include those for the specified artist account.",
      "required": false,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Tasks retrieved successfully",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/TasksResponse"
          }
        }
      }
    },
    "400": {
      "description": "Bad request",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized - missing or invalid credentials",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden - account_id is outside caller authorization scope",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "500": {
      "description": "Internal server error while retrieving tasks.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}