Check Generation Status

GET

Monitor the progress of lead magnet generation jobs

Endpoints

There are two endpoints available for checking generation status:

By Job ID

GET https://magnetite.ai/api/generation/:jobId/status

Use the job ID returned from the generate endpoint

By Lead ID

GET https://magnetite.ai/api/leads/:leadId/job-status

Use the lead ID returned from the generate endpoint

Example Requests

Check by Job ID

curl -X GET https://magnetite.ai/api/generation/job_abc123def456/status \
  -H "Authorization: Bearer YOUR_API_KEY"

Check by Lead ID

curl -X GET https://magnetite.ai/api/leads/lead_xyz789abc123/job-status \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Format

Queued Status

When the job is waiting to be processed:

{
  "success": true,
  "job": {
    "id": "job_abc123def456",
    "leadId": "lead_xyz789abc123",
    "leadMagnetUrl": "https://acme-corp.go.magnetite.ai/lead_xyz789abc123",
    "projectId": "abc123def456ghi789jkl012mno345pq",
    "status": "queued",
    "currentStep": null,
    "progressPercentage": 0,
    "estimatedTimeRemaining": null,
    "processingTime": 5,
    "createdAt": 1642176000000,
    "updatedAt": 1642176005000,
    "error": null,
    "retryCount": 0,
    "maxRetries": 3,
    "steps": [],
    "statusDisplay": "⏳ Queued",
    "phaseDescription": "Preparing to start generation",
    "isStuck": false,
    "canRetry": false,
    "executionPhases": [
      {
        "name": "Lead generation initiated",
        "status": "completed",
        "description": "Lead record created and queued for processing"
      },
      {
        "name": "Research agent started",
        "status": "pending",
        "description": "Research agent execution and data gathering"
      },
      {
        "name": "Data analysis completed",
        "status": "pending",
        "description": "Research data processed and analyzed"
      },
      {
        "name": "Content generation started",
        "status": "pending",
        "description": "AI generating personalized lead magnet content"
      },
      {
        "name": "Finalizing lead magnet",
        "status": "pending",
        "description": "Saving content and preparing final lead magnet"
      }
    ]
  }
}

Processing Status

When the job is actively being processed:

{
  "success": true,
  "job": {
    "id": "job_abc123def456",
    "leadId": "lead_xyz789abc123",
    "leadMagnetUrl": "https://acme-corp.go.magnetite.ai/lead_xyz789abc123",
    "projectId": "abc123def456ghi789jkl012mno345pq",
    "status": "content_running",
    "currentStep": "Generating personalized content",
    "progressPercentage": 65,
    "estimatedTimeRemaining": 45,
    "processingTime": 75,
    "createdAt": 1642176000000,
    "updatedAt": 1642176075000,
    "error": null,
    "retryCount": 0,
    "maxRetries": 3,
    "steps": [
      {
        "name": "research_agent",
        "status": "completed",
        "startedAt": 1642176005000,
        "completedAt": 1642176045000,
        "duration": 40
      },
      {
        "name": "content_generation",
        "status": "running",
        "startedAt": 1642176045000,
        "progress": 65
      }
    ],
    "statusDisplay": "✨ Generating content",
    "phaseDescription": "AI is generating your personalized lead magnet",
    "isStuck": false,
    "canRetry": false,
    "executionPhases": [
      {
        "name": "Lead generation initiated",
        "status": "completed",
        "description": "Lead record created and queued for processing"
      },
      {
        "name": "Research agent started",
        "status": "completed",
        "description": "Research agent execution and data gathering"
      },
      {
        "name": "Data analysis completed",
        "status": "completed",
        "description": "Research data processed and analyzed"
      },
      {
        "name": "Content generation started",
        "status": "current",
        "description": "AI generating personalized lead magnet content"
      },
      {
        "name": "Finalizing lead magnet",
        "status": "pending",
        "description": "Saving content and preparing final lead magnet"
      }
    ]
  }
}

Completed Status

When the job has finished successfully:

{
  "success": true,
  "job": {
    "id": "job_abc123def456",
    "leadId": "lead_xyz789abc123",
    "leadMagnetUrl": "https://acme-corp.go.magnetite.ai/lead_xyz789abc123",
    "projectId": "abc123def456ghi789jkl012mno345pq",
    "status": "completed",
    "currentStep": "Completed",
    "progressPercentage": 100,
    "estimatedTimeRemaining": 0,
    "processingTime": 127,
    "createdAt": 1642176000000,
    "updatedAt": 1642176127000,
    "error": null,
    "retryCount": 0,
    "maxRetries": 3,
    "steps": [
      {
        "name": "research_agent",
        "status": "completed",
        "startedAt": 1642176005000,
        "completedAt": 1642176045000,
        "duration": 40
      },
      {
        "name": "content_generation",
        "status": "completed",
        "startedAt": 1642176045000,
        "completedAt": 1642176115000,
        "duration": 70
      },
      {
        "name": "finalization",
        "status": "completed",
        "startedAt": 1642176115000,
        "completedAt": 1642176127000,
        "duration": 12
      }
    ],
    "statusDisplay": "✅ Completed",
    "phaseDescription": "Lead magnet ready!",
    "isStuck": false,
    "canRetry": false,
    "executionPhases": [
      {
        "name": "Lead generation initiated",
        "status": "completed",
        "description": "Lead record created and queued for processing"
      },
      {
        "name": "Research agent started",
        "status": "completed",
        "description": "Research agent execution and data gathering"
      },
      {
        "name": "Data analysis completed",
        "status": "completed",
        "description": "Research data processed and analyzed"
      },
      {
        "name": "Content generation started",
        "status": "completed",
        "description": "AI generating personalized lead magnet content"
      },
      {
        "name": "Finalizing lead magnet",
        "status": "completed",
        "description": "Saving content and preparing final lead magnet"
      }
    ]
  }
}

Failed Status

When the job has encountered an error:

{
  "success": true,
  "job": {
    "id": "job_abc123def456",
    "leadId": "lead_xyz789abc123",
    "leadMagnetUrl": "https://acme-corp.go.magnetite.ai/lead_xyz789abc123",
    "projectId": "abc123def456ghi789jkl012mno345pq",
    "status": "failed",
    "currentStep": "Content generation failed",
    "progressPercentage": 45,
    "estimatedTimeRemaining": null,
    "processingTime": 85,
    "createdAt": 1642176000000,
    "updatedAt": 1642176085000,
    "error": "Insufficient data to generate personalized content",
    "retryCount": 1,
    "maxRetries": 3,
    "steps": [
      {
        "name": "research_agent",
        "status": "completed",
        "startedAt": 1642176005000,
        "completedAt": 1642176045000,
        "duration": 40
      },
      {
        "name": "content_generation",
        "status": "failed",
        "startedAt": 1642176045000,
        "failedAt": 1642176085000,
        "error": "Insufficient data to generate personalized content"
      }
    ],
    "statusDisplay": "❌ Failed",
    "phaseDescription": "Generation failed",
    "isStuck": false,
    "canRetry": true,
    "executionPhases": [
      {
        "name": "Lead generation initiated",
        "status": "completed",
        "description": "Lead record created and queued for processing"
      },
      {
        "name": "Research agent started",
        "status": "completed",
        "description": "Research agent execution and data gathering"
      },
      {
        "name": "Data analysis completed",
        "status": "completed",
        "description": "Research data processed and analyzed"
      },
      {
        "name": "Content generation started",
        "status": "failed",
        "description": "AI generating personalized lead magnet content"
      },
      {
        "name": "Finalizing lead magnet",
        "status": "failed",
        "description": "Saving content and preparing final lead magnet"
      }
    ]
  }
}

Status Types

Status	Description	Typical Duration
queued	Job is waiting to be processed	0-30 seconds
research_running	Research agent is gathering data	20-40 seconds
content_running	AI is generating the lead magnet content	30-90 seconds
finalizing	Saving and preparing final lead magnet	5-15 seconds
completed	Lead magnet ready and accessible	-
failed	Generation failed due to an error	-

Polling Best Practices

Rate Limits: Status endpoints are limited to 60 requests per minute. Use appropriate polling intervals to avoid hitting limits.

Recommended Polling Strategy

async function pollJobStatus(jobId, maxAttempts = 30) {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      const status = await checkJobStatus(jobId);
      
      console.log(`Attempt ${attempt}: ${status.status} (${status.progress}%)`);
      
      if (status.status === 'completed') {
        return status.result;
      }
      
      if (status.status === 'failed') {
        throw new Error(`Job failed: ${status.error.message}`);
      }
      
      // Progressive backoff: start with 2s, increase gradually
      const delay = Math.min(2000 + (attempt * 1000), 10000);
      await new Promise(resolve => setTimeout(resolve, delay));
      
    } catch (error) {
      console.error(`Polling error: ${error.message}`);
      if (attempt === maxAttempts) throw error;
    }
  }
  
  throw new Error('Job did not complete within expected time');
}

Error Responses

404 Not Found

Job ID or Lead ID doesn't exist

{
  "error": "Job not found"
}

401 Unauthorized

Invalid or missing API key

{
  "error": "Invalid or expired API key"
}

429 Too Many Requests

Rate limit exceeded (includes rate limit headers)

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1642176060
Content-Type: application/json

{
  "error": "Rate limit exceeded. Try again later.",
  "retryAfter": 60
}

Next Steps

Learn about rate limits and error handling for robust integrations.

Rate Limits →Error Handling →