> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syntage.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Extractions

Extractions are tasks that retrieve data for an entity from a datasource. They are used to collect invoices, tax returns, tax status, tax compliance checks, RPC records, RUG guarantees, Buró de Crédito reports, and other datasource-backed records.

An extraction runs asynchronously. Creating one starts or queues the work, and the returned Extraction resource tracks its status, options, timing, errors, and the number of resources created or updated.

## How Extractions Work

1. Create or retrieve the entity you want to extract data for.
2. Start the extraction with the selected datasource and options.
3. Store the returned extraction ID.
4. Retrieve the extraction until its `status` is `finished` or `failed`.
5. Read the extracted data from the related resource endpoints, such as invoices or tax returns.

If the same extraction is already pending or running for the same entity, extractor, and options, Syntage returns a duplicate extraction response instead of starting the same work again.

For implementation details, see [Extraction request examples](/developers/extraction-request-examples) or [Create an extraction](/api-reference/extractions/create-an-extraction).

## Scheduled Extractions

Use schedulers when the same extraction should run repeatedly, such as a daily invoice extraction or a monthly tax return extraction. A scheduler controls whether the automation is enabled, and scheduler rules define the extractor, options, and cron expression.

Extractor names and options are specific to the data you are extracting. For extraction-backed resources, use the resource page to understand what data is collected and the developer examples for request bodies.

## Extraction Status

| Status    | Description                                                                                                                                                                                                                                                                                                                                                                                                        |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| pending   | The initial extraction status. The extraction is enqueued and waiting to be processed.                                                                                                                                                                                                                                                                                                                             |
| waiting   | The extraction cannot run yet because a prerequisite is still blocking it, such as missing entity information, authorization, an unavailable credential, or an internal dependency.                                                                                                                                                                                                                                |
| running   | The extraction process started and is currently running. The running time varies depending on the extractor type and the entity's transactional volume. Partial data may be available from related resource endpoints during this time.                                                                                                                                                                            |
| finished  | The extraction finished successfully. The extracted data is available from the related resource endpoints.                                                                                                                                                                                                                                                                                                         |
| failed    | The extraction couldn't start or failed during the process. Our internal retry policies weren't able to finish the extraction successfully. We may have partial data available, but new extractions should be created to ensure all the entity's data is available. You can check the [extraction error code](#extraction-error-codes) to understand why it failed and determine whether it can be retried or not. |
| stopping  | The extraction was requested to be stopped by the user. It is in the process of being stopped.                                                                                                                                                                                                                                                                                                                     |
| stopped   | The extraction was stopped by the user after it started running. This extraction is included in billing.                                                                                                                                                                                                                                                                                                           |
| cancelled | The extraction was stopped by the user before it started running. This extraction is not included in billing.                                                                                                                                                                                                                                                                                                      |

## Extraction Error Codes

| Code                 | Description                                                                           | Retryable |
| -------------------- | ------------------------------------------------------------------------------------- | --------- |
| invalid\_credentials | The taxpayer [Credential](/api-reference/ds-mx-sat-credentials) is no longer valid.   | No        |
| login\_failed        | We couldn't authenticate the taxpayer with the datasource.                            | Yes       |
| unrecoverable        | The extraction process failed many times, and we reached a maximum number of retries. | Yes       |
| sat\_unavailable     | We detected that SAT itself is down or unresponsive.                                  | Yes       |
| internal\_error      | We detected an internal error in our own infrastructure.                              | Yes       |
| undefined            | We couldn't determine the error cause and our internal team will investigate it.      | Yes       |