POST
/
v2
/
link
/
bulk_trigger_historical_pull
curl --request POST \
  --url https://api.tryvital.io/v2/link/bulk_trigger_historical_pull \
  --header 'Content-Type: application/json' \
  --header 'x-vital-api-key: <api-key>' \
  --data '{
  "user_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "provider": "oura",
  "wait_for_completion": false
}'
"<any>"

If you are planning to migrate connections, please chat with us through support channels. Link Migration endpoints are disabled by default.

​
Asynchronous execution

The Bulk Trigger Historical Pull endpoint enqueues all trigger requests you submitted to a persistent background operation. It then responds 202 Created immediately afterwards.

You can inspect the status of the resulting background operation through the List Bulk Ops endpoint.

Optionally, you may opt into the wait_for_completion mode, which would respond 200 OK only if the operation does complete within 20 seconds. Otherwise, the endpoint responds 202 Created.

You can trigger historical pull on any number of — or even all — connections through the Bulk Trigger Historical Pull API within a short period of time. Enqueuing is fast and does not disrupt the progress of the background operation.

​
Managing provider API rate limits

Junction transparently batches and throttles the trigger requests. This is to avoid exhausting the provider API rate limits of your Bring Your Own OAuth custom credentials.

You can submit as many trigger requests as needed.

ProviderHistorical Pull triggering Rate
Garmin2 connections every 1 minute
Fitbit, Polar250 connections at a time; no time-based throttling
Strava1 connections every 15 minutes
Oura150 connections every 5 minutes
Withings8 connections every 1 minute, with the assumption of your app using Withings Enterprise Plan.
All other providers8 connections every 1 minute

​
Historical Pull Range

Bulk Trigger Historical Pull respects any restricting User Ingestion Bounds and/or any Team Data Pull Preferences you have specified.

If you have specified a large number of days to pull, you should be aware that:

  1. The background operation will take longer time to run to completion.
  2. It may still cause temporary disruption to data polling and webhook processing, even after the triggering having been throttled.

Authorizations

​
x-vital-api-key
string
header
required

Vital Team API Key

Body

application/json
​
user_ids
string[]
required
​
provider
enum<string>
required

ℹ️ This enum is non-exhaustive.

Available options:
oura,
fitbit,
garmin,
strava,
wahoo,
ihealth,
withings,
google_fit,
dexcom_v3,
polar,
cronometer,
omron,
whoop_v2,
my_fitness_pal_v2,
ultrahuman
​
wait_for_completion
boolean
default:false

Whether or not the endpoint should wait for the Bulk Op to complete before responding.

When wait_for_completion is enabled, the endpoint may respond 200 OK if the Bulk Op takes less than 20 seconds to complete.

Otherwise, the endpoint always responds with 202 Created once the submitted data have been enqueued successfully. You can use the List Bulk Ops endpoint to inspect the progress of the Bulk Op.

Response

200
application/json
Successful Response

The response is of type any.