🔁 Why trigger a manual fetch?#

fetchdocs runs a scheduled fetch for every active connection based on the configured interval. Most clients don't need to do anything beyond that. There are two situations where an on-demand fetch is useful:

• You expose a "Sync now" button in your UI so users can pull in newly added documents without waiting for the next scheduled run.
• A configuration change (new folder, new mailbox, freshly granted permission) has just been applied and you want the connection to pick it up immediately.

🚀 How to trigger a manual fetch#

Send a POST request to the connections/{uuid}/fetch-now endpoint. The uuid is the UUID of the connection you stored when you created or migrated the connection.

You can authenticate with either X-API-Key (environment-wide) or X-Token (UI token bound to a single identity). The endpoint accepts both, exactly like the other connection endpoints.

On success the API responds with 202 Accepted and a body containing the UUID of the fetch that has been queued:

The fetch runs asynchronously. Documents that are picked up will be provisioned to your application via the regular provisioning channel (see Document Provisioning).

🛑 When fetchdocs refuses to trigger a fetch#

To keep manual triggers from being used as a polling mechanism and to avoid duplicate work, fetchdocs enforces two guard rails:

• 5 manual fetches per hour, per connection. When you exceed the limit, the API responds with 429 Too Many Requests and a Retry-After header that tells you how many seconds to wait before retrying.
• Imminent scheduled fetch. If a scheduled fetch is already due to run within the next minute, fetchdocs returns 409 Conflict. The scheduled fetch will run momentarily, so there is no point in queueing a parallel one.

In addition:

• 401 Unauthorized is returned when no valid X-API-Key or X-Token is provided.
• 403 Forbidden is returned when the connection does not belong to the authenticated identity or environment.
• 404 Not Found is returned when the connection UUID does not exist.
• 422 Unprocessable Entity is returned when the connection is not active (for example because it has been disabled or its credentials are invalid). Re-enable or fix the connection before triggering a fetch.

Rate-limit attempts are only counted when the request would actually create a fetch. A request that fails with 409 or 422 does not consume your quota.

📘 API reference

For more information about the API endpoint POST /connections/{uuid}/fetch-now, please refer to the API reference.