Force Refresh Analytics

warning

Analytics endpoints are not available on the Basic plan. Upgrade to Intermediate, Growth or Business plan to access this endpoint.

Overview

The Force Refresh Analytics endpoint triggers a manual re-sync of your connected accounts and a fresh analytics fetch, bypassing the normal scheduled refresh throttle. It's most useful right after you connect a new account, so its analytics populate immediately instead of waiting for the next scheduled fetch.

This endpoint is asynchronous — it dispatches background jobs and returns immediately. The analytics data itself is not included in the response; use the batch_id and percentage fields to track progress. A 10-minute cooldown applies between refreshes, and the cooldown starts the moment a refresh is dispatched (not when it finishes).

Base URL:

https://analyze.oneupapp.io

Endpoint

POST /api/force-fetch

Request Parameters

Parameter	Required	Description
apiKey	Yes	Your personal API key generated from the API Access page. Can be sent as a query parameter or form field.

There are no other body parameters — the refresh applies to all accounts connected to the API key's account.

Sample Request

curl --location --request POST \
"https://analyze.oneupapp.io/api/force-fetch?apiKey=YOUR_API_KEY"

Sample Response

202 Accepted — Data refresh successfully started:

{
  "message": "Data refresh started.",
  "status": "started",
  "is_fetching": true,
  "percentage": 0,
  "last_fetched_at": "2026-08-04T12:34:56+00:00"
}

409 Conflict — A refresh is already in progress:

{
  "message": "A data refresh is already in progress.",
  "status": "already_in_progress",
  "is_fetching": true,
  "batch_id": "a2152aa3-6e6d-439b-9056-d2205f466003",
  "percentage": 42,
  "last_fetched_at": "2026-08-04T12:30:12.000000Z"
}

429 Too Many Requests — Data was recently refreshed and is on cooldown:

{
  "message": "Your data was recently refreshed. Please wait before refreshing again.",
  "status": "cooldown",
  "is_fetching": false,
  "last_fetched_at": "2026-08-04T12:28:04.000000Z",
  "remaining_seconds": 356,
  "next_refresh_available_at": "2026-08-04T12:38:04+00:00"
}

200 OK — No connected accounts were found to refresh:

{
  "message": "No connected accounts found.",
  "status": "no_accounts",
  "is_fetching": false,
  "last_fetched_at": null
}

Response Fields

Field	Description
message	Human-readable status message.
status	Current status: started, already_in_progress, cooldown, no_accounts, or error.
is_fetching	Whether a refresh is currently running.
batch_id	Unique identifier for the active refresh batch. Present on 409 (may be null).
percentage	Completion percentage of the current batch (0–100). Present on 202 and 409.
last_fetched_at	ISO 8601 timestamp of the most recent refresh. Set to the dispatch time when a refresh starts, which is also when the 10-minute cooldown begins. May be null if no refresh has run yet.
remaining_seconds	Seconds remaining before the next refresh is allowed. Present on 429.
next_refresh_available_at	ISO 8601 timestamp of when the next refresh can be triggered. Present on 429.

Error Responses

HTTP Status	Status Value	Description
202	started	Refresh successfully dispatched.
200	no_accounts	The account has no connected social accounts to refresh.
409	already_in_progress	A refresh is already running. Wait for it to complete before triggering another.
429	cooldown	Data was refreshed within the last 10 minutes. Check remaining_seconds for when you can retry.
502	error	Unable to sync account data from the upstream service. Try again shortly.
401	—	Missing or invalid API key: { "message": "Please provide a valid API key" }.
403	—	Basic plan: { "message": "Analytics is not available on the Basic plan. Please upgrade your plan to access this feature." }.

502 Bad Gateway — Upstream account sync failed:

{
  "message": "Unable to fetch account data at the moment. Please try again shortly.",
  "status": "error",
  "is_fetching": false
}

✅ Result: You have successfully triggered an analytics refresh!