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 refreshes analytics for your connected accounts on demand, without waiting for the next scheduled update.

This endpoint is asynchronous: it returns a status, not analytics data. Call the same endpoint again to poll for completion. While a refresh is running, polling returns its current status instead of starting another refresh.

A 10-minute cooldown starts when the analytics refresh finishes. Calls during this period return the completed result. Once the cooldown expires, you can use this endpoint to start another refresh.

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, form field, or JSON body field.

The refresh applies to the supported accounts connected to the API key's account. There are no account, platform, date-range, or batch-ID request parameters. Use the same API key on each poll.

Sample Request

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

How to Refresh Analytics

Start a refresh. Call POST /api/force-fetch with your API key.
Check its progress. If the response asks you to poll_force_fetch, wait the number of seconds in retry_after_seconds, then call the same endpoint again. Repeat while the refresh is running.
Retrieve your analytics. When the status is completed, use the analytics endpoints for your connected platforms to retrieve the updated data.

If the status is completed_with_errors, you can retrieve the available data, but some metrics may be missing. If the refresh is interrupted, try again. A no_accounts response means you need to connect an account first.

Refresh times vary. The response tells you when to check again and when the refresh has finished.

Response Statuses

HTTP Status	`status`	`next_action`	Meaning
`202`	`syncing_accounts`	`poll_force_fetch`	Connected accounts are being refreshed before analytics start.
`202`	`started`	`poll_force_fetch`	An analytics refresh has started.
`202`	`already_in_progress`	`poll_force_fetch`	An analytics refresh is still running.
`200`	`completed`	`retrieve_analytics`	The analytics refresh finished with no recorded job failures.
`200`	`completed_with_errors`	`retrieve_analytics`	The refresh finished, but some jobs failed and metrics may be missing.
`200`	`no_accounts`	`connect_account`	No connected accounts were found to refresh.
`503`	`interrupted`	`retry_refresh`	The analytics refresh was interrupted. Retry the refresh.

Sample Responses

Accounts Are Being Synced

202 Accepted, with Retry-After: 5:

{
  "status": "syncing_accounts",
  "message": "Refreshing connected accounts, then analytics. Call this endpoint again in 5 seconds.",
  "is_fetching": true,
  "batch_id": "a2152aa3-6e6d-439b-9056-d2205f466003",
  "total_jobs": null,
  "processed_jobs": 0,
  "pending_jobs": null,
  "failed_jobs": 0,
  "percentage": 0,
  "retry_after_seconds": 5,
  "next_action": "poll_force_fetch"
}

The batch_id can change when account sync hands off to the analytics refresh. Continue polling the same endpoint; do not send the batch ID as a parameter.

Analytics Refresh Started

202 Accepted, with Retry-After: 5:

{
  "status": "started",
  "message": "Analytics refresh started. Call this endpoint again in 5 seconds.",
  "is_fetching": true,
  "batch_id": "b3152aa3-6e6d-439b-9056-d2205f466004",
  "total_jobs": 20,
  "processed_jobs": 0,
  "pending_jobs": 20,
  "failed_jobs": 0,
  "percentage": 0,
  "retry_after_seconds": 5,
  "next_action": "poll_force_fetch"
}

Analytics Refresh Is Still Running

202 Accepted, with Retry-After: 5:

{
  "status": "already_in_progress",
  "message": "Analytics are still refreshing. Call this endpoint again in 5 seconds; do not request analytics yet.",
  "is_fetching": true,
  "batch_id": "b3152aa3-6e6d-439b-9056-d2205f466004",
  "total_jobs": 24,
  "processed_jobs": 12,
  "pending_jobs": 12,
  "failed_jobs": 0,
  "percentage": 50,
  "retry_after_seconds": 5,
  "next_action": "poll_force_fetch"
}

Job totals can increase as pagination, retry, and child jobs are added. The percentage can decrease when more work is discovered. Completion occurs when every tracked job has reported success or terminal failure; a high percentage alone does not indicate completion.

Analytics Refresh Completed

200 OK:

{
  "status": "completed",
  "message": "Analytics refresh finished. You can now request the analytics.",
  "is_fetching": false,
  "batch_id": null,
  "percentage": 100,
  "total_jobs": 24,
  "processed_jobs": 24,
  "pending_jobs": 0,
  "failed_jobs": 0,
  "last_fetched_at": "2026-09-21T04:30:00.000000Z",
  "remaining_seconds": 590,
  "next_action": "retrieve_analytics"
}

remaining_seconds is the wait before another refresh can start. You do not need to wait for it to reach zero before retrieving analytics. Repeated force-fetch calls during this cooldown return the completed result.

Analytics Refresh Completed with Errors

200 OK:

{
  "status": "completed_with_errors",
  "message": "Analytics refresh finished with errors. Some metrics may be missing; you can request available analytics.",
  "is_fetching": false,
  "batch_id": null,
  "percentage": 100,
  "total_jobs": 24,
  "processed_jobs": 24,
  "pending_jobs": 0,
  "failed_jobs": 2,
  "last_fetched_at": "2026-09-21T04:30:00.000000Z",
  "remaining_seconds": 590,
  "next_action": "retrieve_analytics"
}

Here, 100 means all tracked jobs have finished, including failures. It does not mean every metric is available. The failed-job count applies to the overall refresh, not specifically to the account or platform you intend to query.

Refresh Interrupted

503 Service Unavailable:

{
  "status": "interrupted",
  "message": "Analytics refresh was interrupted. Retry the refresh.",
  "is_fetching": false,
  "batch_id": "b3152aa3-6e6d-439b-9056-d2205f466004",
  "next_action": "retry_refresh"
}

No Connected Accounts

200 OK:

{
  "status": "no_accounts",
  "message": "No connected accounts found. Connect an account before refreshing analytics.",
  "is_fetching": false,
  "batch_id": null,
  "next_action": "connect_account"
}

Response Fields

Fields vary by status; do not assume every response contains all fields.

Field	Description
`status`	Machine-readable state listed in the response-status table.
`message`	Human-readable explanation. Use `status` and `next_action` for client logic rather than matching this text.
`is_fetching`	Whether refresh work is in progress. `false` alone does not imply success: check `status`.
`next_action`	Client instruction: `poll_force_fetch`, `retrieve_analytics`, `retry_refresh`, or `connect_account`.
`batch_id`	Identifier for the active phase, or the interrupted analytics batch. `null` in completed and no-account responses.
`total_jobs`	Total tracked analytics jobs, including added child jobs. `null` during account sync.
`processed_jobs`	Successful plus terminally failed jobs. `0` during account sync.
`pending_jobs`	Jobs still awaiting a terminal result. `null` during account sync; `0` when completed.
`failed_jobs`	Number of recorded terminal job failures; included in `processed_jobs`. `0` during account sync.
`percentage`	Analytics progress: `0` during account sync, `0–99` while running, and `100` for either completed status.
`retry_after_seconds`	Suggested delay before polling this endpoint again. Present on `202`; currently `5`, also sent in the `Retry-After` header.
`last_fetched_at`	ISO 8601 analytics completion timestamp. Present on completed responses; this is when the 10-minute cooldown begins.
`remaining_seconds`	Seconds remaining before another refresh can start. Present on completed responses; it does not delay analytics retrieval.

Authentication and Service Errors

These errors may contain only a message, without the refresh-status fields above.

HTTP Status	Description
`401`	Missing or invalid API key. The default message is `Please provide a valid API key`; invalid-key messages may vary.
`403`	Basic plan: `Analytics is not available on the Basic plan. Please upgrade your plan to access this feature.`
`503`	API-key verification is temporarily unavailable: `We’re temporarily unable to verify your API key. Please try again in a few moments.` This is distinct from a refresh response with `status: interrupted`.

If account sync is temporarily unavailable, the endpoint attempts to refresh analytics using accounts already stored in OneUp.

Overview​

Endpoint​

Request Parameters​

Sample Request​

How to Refresh Analytics​

Response Statuses​

Sample Responses​

Accounts Are Being Synced​

Analytics Refresh Started​

Analytics Refresh Is Still Running​

Analytics Refresh Completed​

Analytics Refresh Completed with Errors​

Refresh Interrupted​

No Connected Accounts​

Response Fields​

Authentication and Service Errors​

Overview

Endpoint

Request Parameters

Sample Request

How to Refresh Analytics

Response Statuses

Sample Responses

Accounts Are Being Synced

Analytics Refresh Started

Analytics Refresh Is Still Running

Analytics Refresh Completed

Analytics Refresh Completed with Errors

Refresh Interrupted

No Connected Accounts

Response Fields

Authentication and Service Errors