Progress & Long-Running Jobs

Some Blue operations run asynchronously on the server — bulk imports and exports, reference-field lookups, AI auto-tagging, cover-image generation, automation executions. These subscriptions push job status to your client as the work proceeds, so you can render a progress bar or refresh a view the moment a job finishes instead of polling.

These are streamed over WebSocket using the graphql-ws protocol at wss://api.blue.cc/graphql — the same path as the HTTP GraphQL endpoint. Open and authenticate the connection first; see Connect & Authenticate for the handshake and credential forms. The examples below show only the subscription documents.

Unlike the entity change-feeds (records, comments, files, …) these are job-status channels, so their payloads vary. Some return a free-form JSON blob (subscribeToImportExportProgress, subscribeToLookupProgress), some a typed progress object (subscribeToAITagProgress, subscribeToCoverGenerationProgress), and the automation/OAuth streams reuse the standard { mutation, node, previousValues } shape described on the Real-time overview. Each section below states which.

subscribeToImportExportProgress

Track a bulk import or export as it runs. Blue runs these as background jobs; this stream reports their lifecycle so you can show a spinner and reload the workspace when the job is DONE.

Request

subscription OnImportExportProgress {
  subscribeToImportExportProgress(projectId: "project_123", userId: "user_123")
}

Parameters

Response

This field returns JSON — there is no sub-selection. Each event is an object of the form { status: 'IN_PROGRESS' | 'DONE' | 'ERROR' }.

{
  "data": {
    "subscribeToImportExportProgress": { "status": "IN_PROGRESS" }
  }
}

A terminal DONE (or ERROR) event is the signal to stop your spinner and refetch:

{
  "data": {
    "subscribeToImportExportProgress": { "status": "DONE" }
  }
}

subscribeToLookupProgress

Track progress while Blue resolves a reference (lookup) field across a workspace — for example, recomputing linked-record values after a field or list changes. Scope it to a single workspace with the filter.

Request

subscription OnLookupProgress {
  subscribeToLookupProgress(filter: { projectId: "project_123" })
}

Parameters

LookupProgressFilter

Response

This field returns JSON — there is no sub-selection. The payload is the progress object published by the server for the matching workspace.

{
  "data": {
    "subscribeToLookupProgress": {
      "projectId": "project_123",
      "progress": 60,
      "processed": 120,
      "total": 200
    }
  }
}

subscribeToAITagProgress

Track AI auto-tagging of records as it runs. When you trigger AI tagging for a workspace, the server processes records in the background and publishes progress to this stream.

Request

subscription OnAITagProgress {
  subscribeToAITagProgress(projectId: "project_123") {
    progress
    count
    maxCount
    operationId
    error
    errorCode
  }
}

Parameters

Response

subscribeToAITagProgress returns an AITagProgress object per event.

{
  "data": {
    "subscribeToAITagProgress": {
      "progress": 0.75,
      "count": 75,
      "maxCount": 100,
      "operationId": "clm4n8qwx000008l0g4oxdqn7",
      "error": false,
      "errorCode": null
    }
  }
}

AITagProgress

subscribeToCoverGenerationProgress

Track AI cover-image generation for records in a workspace. Scope it with the filter.

Request

subscription OnCoverGenerationProgress {
  subscribeToCoverGenerationProgress(filter: { projectId: "project_123" }) {
    mutation
    node {
      projectId
      progress
      processedCount
      totalCount
      status
    }
  }
}

Parameters

CoverGenerationProgressFilter

Response

subscribeToCoverGenerationProgress returns a CoverGenerationProgressPayload per event.

{
  "data": {
    "subscribeToCoverGenerationProgress": {
      "mutation": "UPDATED",
      "node": {
        "projectId": "project_123",
        "progress": 40,
        "processedCount": 4,
        "totalCount": 10,
        "status": "IN_PROGRESS"
      }
    }
  }
}

CoverGenerationProgressPayload

This payload has no previousValues or updatedFields — it is a progress feed, not an entity change-feed.

CoverGenerationProgress

subscribeToAutomation

Stream create, update, and delete events for automation definitions in a workspace — keep an automations panel in sync as automations are added, toggled active/inactive, or removed. This is a config feed (the automation itself), not a feed of automation runs — for runs, use subscribeToAutomationExecution.

Request

subscription OnAutomationChange {
  subscribeToAutomation(projectId: "project_123") {
    mutation
    node {
      id
      isActive
      trigger {
        id
        type
      }
      actions {
        id
        type
      }
    }
    updatedFields
  }
}

Parameters

Response

subscribeToAutomation returns an AutomationSubscriptionPayload per event.

{
  "data": {
    "subscribeToAutomation": {
      "mutation": "UPDATED",
      "node": {
        "id": "clm4n8qwx000008l0g4oxdqn7",
        "isActive": false,
        "trigger": { "id": "clm4n8qwx000108l0abcd1234", "type": "CUSTOM_FIELD_ADDED" },
        "actions": [{ "id": "clm4n8qwx000208l0efgh5678", "type": "ADD_CUSTOM_FIELD" }]
      },
      "updatedFields": ["isActive"]
    }
  }
}

AutomationSubscriptionPayload

Automation

The most useful fields on the node. See Create an automation for the full trigger/action model.

subscribeToAutomationExecution

Stream automation runs for a workspace. Every time an automation fires — by event, on a schedule, or because records started/stopped matching a condition — the server records an AutomationExecution and publishes its status here as it progresses through its batches.

Request

subscription OnAutomationExecution {
  subscribeToAutomationExecution(filter: { projectId: "project_123" }) {
    id
    automationId
    type
    status
    totalTodos
    completedBatches
    failedBatches
    todosAffected
    startedAt
    completedAt
    errorMessage
  }
}

Parameters

AutomationExecutionSubscriptionFilter

Response

subscribeToAutomationExecution returns an AutomationExecution per event.

{
  "data": {
    "subscribeToAutomationExecution": {
      "id": "clm4n8qwx000008l0g4oxdqn7",
      "automationId": "clm4n8qwx000108l0abcd1234",
      "type": "EVENT",
      "status": "IN_PROGRESS",
      "totalTodos": 50,
      "completedBatches": 1,
      "failedBatches": 0,
      "todosAffected": 25,
      "startedAt": "2026-05-29T12:00:00.000Z",
      "completedAt": null,
      "errorMessage": null
    }
  }
}

AutomationExecution

AutomationExecutionStatus

AutomationExecutionType

subscribeToOAuthConnection

Stream create, update, and delete events for OAuth connections in a workspace — third-party integrations (e.g. GitHub) that a workspace has authorized. Use it to reflect connection state in an integrations settings panel as connections are added, renamed, expired, or removed.

Request

subscription OnOAuthConnectionChange {
  subscribeToOAuthConnection(input: { projectId: "project_123" }) {
    mutation
    node {
      id
      name
      provider
      expiredAt
    }
    previousValues {
      id
      name
    }
  }
}

Parameters

SubscribeToOAuthConnectionInput

Response

subscribeToOAuthConnection returns an OAuthConnectionSubscriptionPayload per event.

{
  "data": {
    "subscribeToOAuthConnection": {
      "mutation": "CREATED",
      "node": {
        "id": "clm4n8qwx000008l0g4oxdqn7",
        "name": "Acme GitHub",
        "provider": "GITHUB",
        "expiredAt": null
      },
      "previousValues": null
    }
  }
}

OAuthConnectionSubscriptionPayload

OAuthConnection

OAuthProvider

Permissions

Authentication is enforced at the WebSocket handshake — an unauthenticated connection is rejected before any subscription runs. Beyond that, delivery is gated per event:

• subscribeToImportExportProgress delivers an event only when the job’s userId matches the authenticated user. Pass your own user ID as the userId argument.
• subscribeToAITagProgress delivers an event only to the user who started the tagging job.
• subscribeToAutomation and subscribeToOAuthConnection deliver an event only if you are a member of the workspace the automation or connection belongs to.
• subscribeToLookupProgress, subscribeToCoverGenerationProgress, and subscribeToAutomationExecution deliver events matched on the projectId you supply.

Subscribing always succeeds; you simply receive events only for jobs you can see. See Connect & Authenticate for credentials.

Related

• Real-time (Subscriptions) — the shared payload shape and the full subscription catalog.
• Connect & Authenticate — open and authenticate the WebSocket.
• Automations — create, edit, and delete the automations these streams report on.
• Import & Export — the HTTP side of the jobs subscribeToImportExportProgress tracks.