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

# Refresh Analytics Target

> Trigger an analytics refresh for a target and return refresh metadata

Queues and executes an analytics refresh for a target in the authenticated key
scope (workspace or personal).

## Billing

* If the target is still inside its free refresh window, `wasFree=true` and `credits_used=0`.
* When the free window is exhausted, refresh consumes credits (`credits_used > 0`).
* Seat billing (target upkeep) is charged separately from per-refresh billing.

## Path Parameters

<ParamField path="id" type="string" required>
  Analytics target ID.
</ParamField>

## Response

<ResponseField name="refresh" type="object">
  Refresh row with status, timestamps, and billing metadata.
</ResponseField>

<ResponseField name="wasFree" type="boolean">
  Indicates whether this refresh used the free daily refresh window.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://www.genviral.io/api/partner/v1/analytics/targets/e7a7f417-56db-4320-9e9a-fd6fdabda09d/refresh \
    --header 'Authorization: Bearer <token>'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "ok": true,
    "code": 200,
    "message": "Analytics refresh queued",
    "data": {
      "refresh": {
        "id": "fd8f615f-971e-4f9f-85dc-f8e55fb0a413",
        "target_id": "e7a7f417-56db-4320-9e9a-fd6fdabda09d",
        "workspace_id": "4cb5d3fd-8c8f-4ed7-a17c-4ffb52c7e6ac",
        "status": "pending",
        "free_refresh_used": true,
        "credits_used": 0,
        "started_at": "2026-02-14T16:05:11.025Z",
        "completed_at": null,
        "error": null
      },
      "wasFree": true
    }
  }
  ```
</ResponseExample>

## Error Responses

* `400 missing_target_id` - missing path parameter
* `402` - insufficient credits for paid refresh
* `409 analytics_conflict` - another refresh is already running for this target
* `429 rate_limited` - too many refresh requests for the same target in a short window
* `404` - target not found in authenticated key scope
* `401`/`403` - authentication failed or key lacks required scope access
* `500` - unexpected refresh execution error

All error responses from analytics endpoints include an `error_code` field.