Skip to main content
GET
/
v1
/
extractions
/
{publicId}
Get Job Status
curl --request GET \
  --url https://api.taxo.co/v1/extractions/{publicId}
{
  "error": {
    "code": "EXTRACTION_NOT_FOUND",
    "message": "No extraction found with the provided ID",
    "details": {
      "extractionId": "JOB20250104123456789A"
    }
  }
}

​
Description

This endpoint allows you to query the status and progress of a previously initiated extraction job. Use the job’s publicId to track progress until completion.
We recommend using webhooks to receive automatic notifications instead of constant polling.

​
Parameters

​
publicId
string
required
Unique public ID of the job obtained when creating the extraction (e.g., “JOB20250104123456789A”)

​
Response

​
publicId
string
Unique extraction ID
​
status
string
Current extraction status:
  • PENDING: In queue, waiting to be processed
  • PROCESSING: Extracting documents from SAT
  • COMPLETED: Successfully completed
  • FAILED: Failed due to unrecoverable error
​
createdAt
string
Creation timestamp in ISO 8601 format
​
updatedAt
string
Last update timestamp
​
completedAt
string
Completion timestamp (only when status is COMPLETED or FAILED)
​
options
object
Original extraction options
​
subject
object
Taxpayer information
​
progress
object
Extraction progress information
​
documents
array
List of extracted documents (only when status is COMPLETED)
​
error
object
Error information (only when status is FAILED)

​
Examples

curl -X GET "https://api.taxo.co/v1/extractions/JOB20250104123456789A" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Example responses

{
  "publicId": "JOB20250104123456789A",
  "status": "PROCESSING",
  "createdAt": "2025-01-04T12:34:56.789Z",
  "updatedAt": "2025-01-04T12:45:23.456Z",
  "options": {
    "informationType": "INVOICE",
    "period": {
      "from": "2024-01-01",
      "to": "2024-12-31"
    },
    "direction": "RECEIVED"
  },
  "subject": {
    "identification": "ABC010101ABC",
    "fullName": "Empresa ABC S.A. de C.V.",
    "personType": "MORAL"
  },
  "progress": {
    "discoveryCount": 1500,
    "completedCount": 750,
    "failedCount": 2,
    "percentage": 50,
    "estimatedTimeRemaining": "PT15M"
  }
}

​
Efficient polling implementation

async function pollUntilComplete(extractionId, maxAttempts = 120) {
  const delays = [5, 10, 20, 30, 60]; // seconds
  let attempt = 0;
  
  while (attempt < maxAttempts) {
    try {
      const status = await getExtractionStatus(extractionId);
      
      console.log(`Attempt ${attempt + 1}: ${status.status} - ${status.progress.percentage}%`);
      
      if (status.status === 'COMPLETED') {
        console.log(`✅ Extraction completed: ${status.progress.completedCount} documents`);
        return status;
      }
      
      if (status.status === 'FAILED') {
        throw new Error(`❌ Extraction failed: ${status.error.message}`);
      }
      
      // Calculate delay with exponential backoff
      const delayIndex = Math.min(attempt, delays.length - 1);
      const delay = delays[delayIndex] * 1000;
      
      console.log(`⏳ Waiting ${delays[delayIndex]} seconds...`);
      await new Promise(resolve => setTimeout(resolve, delay));
      
      attempt++;
      
    } catch (error) {
      console.error('Error querying status:', error);
      throw error;
    }
  }
  
  throw new Error('Timeout: The extraction did not complete within the expected time');
}

// Usage
try {
  const result = await pollUntilComplete('JOB20250104123456789A');
  console.log('Available documents:', result.documents.length);
} catch (error) {
  console.error('Polling error:', error.message);
}

​
Extraction states

The extraction is in queue waiting to be processed. This may take a few minutes during peak hours.
The extraction is in progress. The progress.percentage field shows the current progress.
The extraction completed successfully. Documents are available for download.
The extraction failed due to an unrecoverable error. Check the error field for more details.

​
Error codes

{
  "error": {
    "code": "EXTRACTION_NOT_FOUND",
    "message": "No extraction found with the provided ID",
    "details": {
      "extractionId": "JOB20250104123456789A"
    }
  }
}
Optimization: Instead of frequent polling, configure webhooks to receive automatic notifications when the extraction completes.