Skip to main content

Jobs API

The Jobs API allows you to track background jobs, such as competitor analysis, battlecard generation, and other asynchronous operations.

List Jobs​

Get jobs for your workspace. Supports filtering by competitor ID, type, status, and limit.

GET /api/jobs?competitorId={competitorId}&type={type}&status={status}&limit={limit}

Query Parameters​

  • competitorId (string, optional) - Filter jobs by competitor ID. If provided, queries jobs for that competitor. Otherwise, queries workspace-level jobs.
  • type (string, optional) - Filter by job type (e.g., 'discover-products', 'discover-profile', 'collect')
  • status (string, optional) - Filter by status: 'running', 'completed', or 'failed'
  • limit (integer, optional) - Limit number of results

Response​

{
  "jobs": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "workspaceId": "workspace-id",
      "competitorId": "competitor-id",
      "type": "collect",
      "displayTitle": "Analyzing Competitor",
      "status": "running",
      "progress": 50,
      "currentStep": "Processing Intel",
      "steps": [
        {
          "id": "collect",
          "name": "Collecting Intel",
          "status": "completed"
        },
        {
          "id": "ingest",
          "name": "Processing Intel",
          "status": "running"
        },
        {
          "id": "build-matrix",
          "name": "Building Competitor Matrix",
          "status": "pending"
        },
        {
          "id": "build-battlecard",
          "name": "Generating Battle Card",
          "status": "pending"
        }
      ],
      "startedAt": "2024-01-01T00:00:00.000Z",
      "completedAt": null,
      "metadata": {
        "competitorName": "Competitor Inc",
        "isFirstRun": true,
        "productIds": ["product-id-1"]
      }
    }
  ]
}

Status Values​

  • running - Job is currently in progress
  • completed - Job completed successfully
  • failed - Job failed with an error

Step Status Values​

  • pending - Step hasn't started yet
  • running - Step is currently running
  • completed - Step completed successfully
  • failed - Step failed

Job Types​

  • collect - Competitor data collection and analysis
  • discover-products - Product discovery for a competitor
  • discover-profile - Profile discovery for a competitor
  • analyze-product-capabilities - Product capability analysis
  • Other job types may be added over time

Get Job​

Get a specific job by ID.

GET /api/jobs/{id}

Path Parameters​

  • id (string, required) - Job ID

Response​

{
  "job": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "workspaceId": "workspace-id",
    "competitorId": "competitor-id",
    "type": "collect",
    "displayTitle": "Analyzing Competitor",
    "status": "running",
    "progress": 50,
    "currentStep": "Processing Intel",
    "steps": [
      {
        "id": "collect",
        "name": "Collecting Intel",
        "status": "completed"
      },
      {
        "id": "ingest",
        "name": "Processing Intel",
        "status": "running"
      }
    ],
    "startedAt": "2024-01-01T00:00:00.000Z",
    "completedAt": null,
    "metadata": {
      "competitorName": "Competitor Inc",
      "isFirstRun": true
    }
  }
}

Cancel Job​

Cancel a running job.

POST /api/jobs/{id}/cancel

Path Parameters​

  • id (string, required) - Job ID

Response​

{
  "success": true,
  "job": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "failed",
    "currentStep": "Cancelled"
  }
}

Error Responses​

  • 400 - Bad Request (invalid parameters)
  • 401 - Unauthorized (invalid or missing API key)
  • 404 - Not Found (job doesn't exist)

Polling Jobs​

To track job progress, poll the job endpoint:

# Poll every 2 seconds until completed
while true; do
  response=$(curl -H "X-API-Key: your-api-key" \
    https://app.hellobattlecard.com/api/jobs/job-id)
  
  status=$(echo $response | jq -r '.job.status')
  
  if [ "$status" = "completed" ] || [ "$status" = "failed" ]; then
    echo "Job finished with status: $status"
    break
  fi
  
  sleep 2
done