Signal API
Google Analytics as MarkdownUse a clean Markdown version of this page with an agent or local tooling.

Google Analytics

Connect GA4 and read referral, conversion, and landing-page analytics.

Package and capabilitiesThe assigned package must set advanced.google_analytics_enabled to true. Analytics reads require analytics:read; connection and configuration operations require analytics:write.
Base URLhttps://api.signal.ceyo.ai/v1
Project and location scopeUse /projects/{project_id}/analytics for a standard project or /projects/{project_id}/locations/{location_id}/analytics for a location. IDs may be Signal UUIDs or partner external IDs.
1. Start authorizationCall POST /analytics/connect at the selected scope and send the user to the returned authorization_url.
2. Complete the callbackGoogle returns to Signal's public callback, which validates the API key and scope stored in state and exchanges the code.
3. Select a propertyList accounts and properties, then call PUT /analytics/select_property. To use partner-managed credentials instead, configure a token source and call PUT /analytics/external_source.
4. SyncQueue collection with POST /analytics/sync.
GET
{scope}/analytics

Returns the GA4 overview for a project or location.

Parameters

Project path parameters

project_idproject UUID | project external ID

Project identifier.

Required
Parameters

Location path parameters

project_idproject UUID | project external ID

Project identifier.

Required
location_idlocation UUID | location external ID

Location identifier belonging to the project.

Required
Parameters

Query parameters

daysinteger

Reporting window. Values are clamped to 7–90 days.

OptionalDefault: 30
Response

Response body

summary:objectdaily_series:object[]platforms:object[]conversion_summary:objectaction_markers:object[]connection:objectdays:integer
summaryobject

Traffic and conversion totals with trends.

daily_seriesobject[]

Daily analytics points.

platformsobject[]

AI platform breakdown.

conversion_summaryobject

Conversion totals.

action_markersobject[]

Completed action markers in the window.

connectionobject

Current GA4 connection summary.

daysinteger

Applied reporting window.

ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "name",
        "message": "must be present"
      }
    ],
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}
Errors

Status codes

401invalid_api_key

The API key is absent or invalid.

403forbidden | analytics_unavailable

The key lacks access or GA4 is not enabled by the package.

404not_found

The scope or requested analytics resource was not found.

422validation_failed | analytics_not_connected

Input is invalid or the connection is not ready.

429google_rate_limited

Google Analytics temporarily rate limited the request.

502google_unavailable | external_token_unavailable | external_token_unauthorized

Google or an external token provider is temporarily unavailable.

GET
{scope}/analytics/referrals

Returns earned referral sources and their GA4 traffic.

Parameters

Project path parameters

project_idproject UUID | project external ID

Project identifier.

Required
Parameters

Location path parameters

project_idproject UUID | project external ID

Project identifier.

Required
location_idlocation UUID | location external ID

Location identifier belonging to the project.

Required
Parameters

Query parameters

daysinteger

Reporting window. Values are clamped to 7–90 days.

OptionalDefault: 30
pageinteger

1-based page number. Each page contains 25 records.

OptionalDefault: 1
Response

Response body

sources:object[]sources_pagination:Paginationhero:objectsummary:string | nulldays:integer
sourcesobject[]

Referral sources for the requested page.

sources_paginationPagination

25-item pagination metadata.

heroobject

Headline referral metrics.

summarystring | null

Generated referral summary when available.

daysinteger

Applied reporting window.

ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "name",
        "message": "must be present"
      }
    ],
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}
Errors

Status codes

401invalid_api_key

The API key is absent or invalid.

403forbidden | analytics_unavailable

The key lacks access or GA4 is not enabled by the package.

404not_found

The scope or requested analytics resource was not found.

422validation_failed | analytics_not_connected

Input is invalid or the connection is not ready.

429google_rate_limited

Google Analytics temporarily rate limited the request.

502google_unavailable | external_token_unavailable | external_token_unauthorized

Google or an external token provider is temporarily unavailable.

GET
{scope}/analytics/conversions

Returns conversion performance, optionally filtered by GA4 key event.

Parameters

Project path parameters

project_idproject UUID | project external ID

Project identifier.

Required
Parameters

Location path parameters

project_idproject UUID | project external ID

Project identifier.

Required
location_idlocation UUID | location external ID

Location identifier belonging to the project.

Required
Parameters

Query parameters

daysinteger

Reporting window. Values are clamped to 7–90 days.

OptionalDefault: 30
event_namesstring | string[]

Comma-separated or repeated key event names. Maximum: 50.

Optional
Response

Response body

hero:objectrate_by_source:object[]by_platform:object[]summary:string | nulldays:integerapplied_event_names:string[]
heroobject

Headline conversion metrics.

rate_by_sourceobject[]

Conversion rates by source.

by_platformobject[]

Conversion metrics by channel.

summarystring | null

Generated conversion summary when available.

daysinteger

Applied reporting window.

applied_event_namesstring[]

Normalized event filter.

ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "name",
        "message": "must be present"
      }
    ],
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}
Errors

Status codes

401invalid_api_key

The API key is absent or invalid.

403forbidden | analytics_unavailable

The key lacks access or GA4 is not enabled by the package.

404not_found

The scope or requested analytics resource was not found.

422validation_failed | analytics_not_connected

Input is invalid or the connection is not ready.

429google_rate_limited

Google Analytics temporarily rate limited the request.

502google_unavailable | external_token_unavailable | external_token_unauthorized

Google or an external token provider is temporarily unavailable.

GET
{scope}/analytics/conversion_events

Lists observed GA4 key events for conversion filtering.

Parameters

Project path parameters

project_idproject UUID | project external ID

Project identifier.

Required
Parameters

Location path parameters

project_idproject UUID | project external ID

Project identifier.

Required
location_idlocation UUID | location external ID

Location identifier belonging to the project.

Required
Parameters

Query parameters

daysinteger

Reporting window. Values are clamped to 7–180 days.

OptionalDefault: 90
Response

Response body

events:{ name, total_key_events }[]days:integerlimit:integer
events{ name, total_key_events }[]

Up to 200 key events, ordered by count.

daysinteger

Applied reporting window.

limitinteger

Maximum returned event count.

ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "name",
        "message": "must be present"
      }
    ],
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}
Errors

Status codes

401invalid_api_key

The API key is absent or invalid.

403forbidden | analytics_unavailable

The key lacks access or GA4 is not enabled by the package.

404not_found

The scope or requested analytics resource was not found.

422validation_failed | analytics_not_connected

Input is invalid or the connection is not ready.

429google_rate_limited

Google Analytics temporarily rate limited the request.

502google_unavailable | external_token_unavailable | external_token_unauthorized

Google or an external token provider is temporarily unavailable.

GET
{scope}/analytics/landing_pages

Returns AI landing-page performance and platform distribution.

Parameters

Project path parameters

project_idproject UUID | project external ID

Project identifier.

Required
Parameters

Location path parameters

project_idproject UUID | project external ID

Project identifier.

Required
location_idlocation UUID | location external ID

Location identifier belonging to the project.

Required
Parameters

Query parameters

daysinteger

Reporting window. Values are clamped to 7–90 days.

OptionalDefault: 30
pageinteger

1-based page number. Each page contains 25 records.

OptionalDefault: 1
matrix_pageinteger

1-based page for the 25-item platform matrix.

OptionalDefault: 1
Response

Response body

pages:object[]pages_pagination:Paginationhero:objectplatform_matrix:objectmatrix_pagination:Paginationdays:integer
pagesobject[]

Landing-page metrics.

pages_paginationPagination

Landing-page pagination.

heroobject

Headline landing-page metrics.

platform_matrixobject

Platform names, colors, and paged rows.

matrix_paginationPagination

Platform matrix pagination.

daysinteger

Applied reporting window.

ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "name",
        "message": "must be present"
      }
    ],
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}
Errors

Status codes

401invalid_api_key

The API key is absent or invalid.

403forbidden | analytics_unavailable

The key lacks access or GA4 is not enabled by the package.

404not_found

The scope or requested analytics resource was not found.

422validation_failed | analytics_not_connected

Input is invalid or the connection is not ready.

429google_rate_limited

Google Analytics temporarily rate limited the request.

502google_unavailable | external_token_unavailable | external_token_unauthorized

Google or an external token provider is temporarily unavailable.

GET
{scope}/analytics/connection

Returns the current connection for a project or location.

Parameters

Project path parameters

project_idproject UUID | project external ID

Project identifier.

Required
Parameters

Location path parameters

project_idproject UUID | project external ID

Project identifier.

Required
location_idlocation UUID | location external ID

Location identifier belonging to the project.

Required
Response

Response body

project_id:uuidlocation_id:uuidconnection:Connection
project_iduuid

Resolved project ID.

location_iduuid

Resolved location ID when location-scoped.

connectionConnection

Connection details, or disconnected status.

Object

Connection

iduuid

Connection identifier.

statusconnected | disconnected | revoked | error

Current connection status.

auth_strategyceyo_oauth | external_token_source

Credential strategy.

account_idstring | null

Selected GA4 account.

property_idstring | null

Selected GA4 property.

last_synced_atdatetime | null

Most recent completed sync.

syncing_sincedatetime | null

Start time of the active sync.

error_messagestring | null

Most recent connection error.

ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "name",
        "message": "must be present"
      }
    ],
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}
Errors

Status codes

401invalid_api_key

The API key is absent or invalid.

403forbidden | analytics_unavailable

The key lacks access or GA4 is not enabled by the package.

404not_found

The scope or requested analytics resource was not found.

422validation_failed | analytics_not_connected

Input is invalid or the connection is not ready.

429google_rate_limited

Google Analytics temporarily rate limited the request.

502google_unavailable | external_token_unavailable | external_token_unauthorized

Google or an external token provider is temporarily unavailable.

POST
{scope}/analytics/connect

Creates a short-lived Google OAuth authorization URL.

Parameters

Project path parameters

project_idproject UUID | project external ID

Project identifier.

Required
Parameters

Location path parameters

project_idproject UUID | project external ID

Project identifier.

Required
location_idlocation UUID | location external ID

Location identifier belonging to the project.

Required
Response

Response body

authorization_url:URL

Google authorization URL.

CallbackGoogle returns to /v1/google_analytics/oauth/callback, which completes the exchange. Poll the connection endpoint after the browser reports success.
ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "name",
        "message": "must be present"
      }
    ],
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}
Errors

Status codes

401invalid_api_key

The API key is absent or invalid.

403forbidden | analytics_unavailable

The key lacks access or GA4 is not enabled by the package.

404not_found

The scope or requested analytics resource was not found.

422validation_failed | analytics_not_connected

Input is invalid or the connection is not ready.

429google_rate_limited

Google Analytics temporarily rate limited the request.

502google_unavailable | external_token_unavailable | external_token_unauthorized

Google or an external token provider is temporarily unavailable.

POST
{scope}/analytics/exchange

Exchanges a Google authorization code for a scoped connection.

Parameters

Project path parameters

project_idproject UUID | project external ID

Project identifier.

Required
Parameters

Location path parameters

project_idproject UUID | project external ID

Project identifier.

Required
location_idlocation UUID | location external ID

Location identifier belonging to the project.

Required
Parameters

Request body

codestring

Authorization code returned by Google.

Required
statestring

Unmodified state from the authorization flow.

Required
Response

Response body

connected:trueconnection_id:uuidstatus:string
connectedtrue

Confirms that credentials were stored.

connection_iduuid

Connection identifier.

statusstring

Current connection status.

ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "name",
        "message": "must be present"
      }
    ],
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}
Errors

Status codes

401invalid_api_key

The API key is absent or invalid.

403forbidden | analytics_unavailable

The key lacks access or GA4 is not enabled by the package.

404not_found

The scope or requested analytics resource was not found.

422validation_failed | analytics_not_connected

Input is invalid or the connection is not ready.

429google_rate_limited

Google Analytics temporarily rate limited the request.

502google_unavailable | external_token_unavailable | external_token_unauthorized

Google or an external token provider is temporarily unavailable.

GET
{scope}/analytics/accounts

Lists Google Analytics accounts available to the connection.

Parameters

Project path parameters

project_idproject UUID | project external ID

Project identifier.

Required
Parameters

Location path parameters

project_idproject UUID | project external ID

Project identifier.

Required
location_idlocation UUID | location external ID

Location identifier belonging to the project.

Required
Response

Response body

accounts:object[]

Available GA4 account summaries.

CapabilityThis connection setup endpoint requires analytics:write.
ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "name",
        "message": "must be present"
      }
    ],
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}
Errors

Status codes

401invalid_api_key

The API key is absent or invalid.

403forbidden | analytics_unavailable

The key lacks access or GA4 is not enabled by the package.

404not_found

The scope or requested analytics resource was not found.

422validation_failed | analytics_not_connected

Input is invalid or the connection is not ready.

429google_rate_limited

Google Analytics temporarily rate limited the request.

502google_unavailable | external_token_unavailable | external_token_unauthorized

Google or an external token provider is temporarily unavailable.

GET
{scope}/analytics/properties

Lists GA4 properties for an available account.

Parameters

Project path parameters

project_idproject UUID | project external ID

Project identifier.

Required
Parameters

Location path parameters

project_idproject UUID | project external ID

Project identifier.

Required
location_idlocation UUID | location external ID

Location identifier belonging to the project.

Required
Parameters

Query parameters

account_idstring

Google Analytics account identifier.

Required
Response

Response body

properties:object[]

GA4 properties in the account.

CapabilityThis connection setup endpoint requires analytics:write.
ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "name",
        "message": "must be present"
      }
    ],
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}
Errors

Status codes

401invalid_api_key

The API key is absent or invalid.

403forbidden | analytics_unavailable

The key lacks access or GA4 is not enabled by the package.

404not_found

The scope or requested analytics resource was not found.

422validation_failed | analytics_not_connected

Input is invalid or the connection is not ready.

429google_rate_limited

Google Analytics temporarily rate limited the request.

502google_unavailable | external_token_unavailable | external_token_unauthorized

Google or an external token provider is temporarily unavailable.

PUT
{scope}/analytics/select_property

Selects the GA4 property and queues an initial sync.

Parameters

Project path parameters

project_idproject UUID | project external ID

Project identifier.

Required
Parameters

Location path parameters

project_idproject UUID | project external ID

Project identifier.

Required
location_idlocation UUID | location external ID

Location identifier belonging to the project.

Required
Parameters

Request body

property_idstring

GA4 property identifier.

Required
property_namestring

Property display name.

Optional
account_idstring

Parent account identifier.

Required
account_namestring

Parent account display name.

Optional
Response

Response body

selected:trueconnection:Connection
selectedtrue

Confirms the selection.

connectionConnection

Updated connection.

ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "name",
        "message": "must be present"
      }
    ],
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}
Errors

Status codes

401invalid_api_key

The API key is absent or invalid.

403forbidden | analytics_unavailable

The key lacks access or GA4 is not enabled by the package.

404not_found

The scope or requested analytics resource was not found.

422validation_failed | analytics_not_connected

Input is invalid or the connection is not ready.

429google_rate_limited

Google Analytics temporarily rate limited the request.

502google_unavailable | external_token_unavailable | external_token_unauthorized

Google or an external token provider is temporarily unavailable.

PUT
{scope}/analytics/external_source

Connects a scope through a workspace token source.

Parameters

Project path parameters

project_idproject UUID | project external ID

Project identifier.

Required
Parameters

Location path parameters

project_idproject UUID | project external ID

Project identifier.

Required
location_idlocation UUID | location external ID

Location identifier belonging to the project.

Required
Parameters

Request body

token_source_iduuid

Enabled workspace token source.

Required
external_resource_idstring

Resource ID sent to the partner endpoint.

Required
property_idstring

GA4 property ID. Required before syncing.

Optional
property_namestring

GA4 property display name.

Optional
account_idstring

GA4 account ID.

Optional
account_namestring

GA4 account display name.

Optional
Response

Response body

connected:trueconnection:Connection
connectedtrue

Confirms the external connection.

connectionConnection

Updated connection.

ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "name",
        "message": "must be present"
      }
    ],
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}
Errors

Status codes

401invalid_api_key

The API key is absent or invalid.

403forbidden | analytics_unavailable

The key lacks access or GA4 is not enabled by the package.

404not_found

The scope or requested analytics resource was not found.

422validation_failed | analytics_not_connected

Input is invalid or the connection is not ready.

429google_rate_limited

Google Analytics temporarily rate limited the request.

502google_unavailable | external_token_unavailable | external_token_unauthorized

Google or an external token provider is temporarily unavailable.

POST
{scope}/analytics/sync

Queues GA4 collection for the selected property.

Parameters

Project path parameters

project_idproject UUID | project external ID

Project identifier.

Required
Parameters

Location path parameters

project_idproject UUID | project external ID

Project identifier.

Required
location_idlocation UUID | location external ID

Location identifier belonging to the project.

Required
Parameters

Request body

force_fullJSON boolean

Requests a full refresh instead of an incremental sync; strings are rejected.

OptionalDefault: false
Response

202 response body

queued:true

Returned with 202 Accepted.

ConcurrencyA request made during an active sync returns 409 sync_in_progress.
ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "name",
        "message": "must be present"
      }
    ],
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}
Errors

Status codes

401invalid_api_key

The API key is absent or invalid.

403forbidden | analytics_unavailable

The key lacks access or GA4 is not enabled by the package.

404not_found

The scope or requested analytics resource was not found.

409sync_in_progress

A Google Analytics sync is already in progress.

422validation_failed | analytics_not_connected

Input is invalid or the connection is not ready.

429google_rate_limited

Google Analytics temporarily rate limited the request.

502google_unavailable | external_token_unavailable | external_token_unauthorized

Google or an external token provider is temporarily unavailable.

DELETE
{scope}/analytics/connection

Disconnects GA4 and removes all stored analytics for the scope.

Parameters

Project path parameters

project_idproject UUID | project external ID

Project identifier.

Required
Parameters

Location path parameters

project_idproject UUID | project external ID

Project identifier.

Required
location_idlocation UUID | location external ID

Location identifier belonging to the project.

Required
Destructive operationDisconnecting clears credentials, the selected property, and collected daily and event metrics.
Response

Response body

disconnected:true

Confirms the connection was removed.

ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "name",
        "message": "must be present"
      }
    ],
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}
Errors

Status codes

401invalid_api_key

The API key is absent or invalid.

403forbidden | analytics_unavailable

The key lacks access or GA4 is not enabled by the package.

404not_found

The scope or requested analytics resource was not found.

422validation_failed | analytics_not_connected

Input is invalid or the connection is not ready.

429google_rate_limited

Google Analytics temporarily rate limited the request.

502google_unavailable | external_token_unavailable | external_token_unauthorized

Google or an external token provider is temporarily unavailable.

GET
/google_analytics_token_sources

Lists external token sources in the API key workspace.

Response

Response body

token_sources:TokenSource[]

Workspace token sources ordered by name.

Object

TokenSource

iduuid

Token source identifier.

namestring

Workspace-unique display name.

strategyexternal_token_endpoint

Credential strategy.

enabledboolean

Whether new token requests are allowed.

endpoint_urlURL

Partner endpoint that returns a Google access token.

http_methodGET | POST

HTTP method used to request a token.

service_key_headerstring

Header used to send the service key.

has_service_keyboolean

Whether an encrypted service key is stored.

header_namesstring[]

Configured custom header names; values are never returned.

request_resource_id_keystring

Request field used for the external resource identifier.

attached_scope_countinteger

Number of attached project or location scopes.

CapabilityAll token source endpoints, including this list, require workspace-scoped analytics:write.
ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "name",
        "message": "must be present"
      }
    ],
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}
Errors

Status codes

401invalid_api_key

The API key is absent or invalid.

403forbidden

The key lacks workspace analytics:write access.

404not_found

The token source was not found in this workspace.

422validation_failed | limit_reached

Input is invalid or the workspace limit was reached.

POST
/google_analytics_token_sources

Creates an external token endpoint configuration.

Parameters

Request body

namestring

Workspace-unique display name.

Required
strategyexternal_token_endpoint

Token source strategy.

Required
endpoint_urlURL

HTTPS endpoint that returns a Google access token.

Required
http_methodGET | POST

Method used to call the endpoint.

Required
service_key_headerstring

Header name for the service key.

Required
service_keystring

Optional secret value. It is encrypted and never returned.

Optional
request_resource_id_keystring

Request field for external_resource_id.

Required
enabledboolean

Enables or disables the source.

Required
headersobject

Optional request headers with scalar values.

Optional
Response

201 response body

token_source:TokenSource

Created token source. Returns 201.

Object

TokenSource

iduuid

Token source identifier.

namestring

Workspace-unique display name.

strategyexternal_token_endpoint

Credential strategy.

enabledboolean

Whether new token requests are allowed.

endpoint_urlURL

Partner endpoint that returns a Google access token.

http_methodGET | POST

HTTP method used to request a token.

service_key_headerstring

Header used to send the service key.

has_service_keyboolean

Whether an encrypted service key is stored.

header_namesstring[]

Configured custom header names; values are never returned.

request_resource_id_keystring

Request field used for the external resource identifier.

attached_scope_countinteger

Number of attached project or location scopes.

ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "name",
        "message": "must be present"
      }
    ],
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}
Errors

Status codes

401invalid_api_key

The API key is absent or invalid.

403forbidden

The key lacks workspace analytics:write access.

404not_found

The token source was not found in this workspace.

422validation_failed | limit_reached

Input is invalid or the workspace limit was reached.

PATCH
/google_analytics_token_sources/{id}

Updates a workspace token source.

Parameters

Path parameters

iduuid

Token source identifier.

Required
Parameters

Request body

namestring

Workspace-unique display name.

Optional
strategyexternal_token_endpoint

Token source strategy.

Optional
endpoint_urlURL

HTTPS endpoint that returns a Google access token.

Optional
http_methodGET | POST

Method used to call the endpoint.

Optional
service_key_headerstring

Header name for the service key.

Optional
service_keystring

Replacement secret. Omit or send blank to keep the existing value.

Optional
request_resource_id_keystring

Request field for external_resource_id.

Optional
enabledboolean

Enables or disables the source.

Optional
headersobject

Optional request headers with scalar values.

Optional
Response

Response body

token_source:TokenSource

Updated token source.

Object

TokenSource

iduuid

Token source identifier.

namestring

Workspace-unique display name.

strategyexternal_token_endpoint

Credential strategy.

enabledboolean

Whether new token requests are allowed.

endpoint_urlURL

Partner endpoint that returns a Google access token.

http_methodGET | POST

HTTP method used to request a token.

service_key_headerstring

Header used to send the service key.

has_service_keyboolean

Whether an encrypted service key is stored.

header_namesstring[]

Configured custom header names; values are never returned.

request_resource_id_keystring

Request field used for the external resource identifier.

attached_scope_countinteger

Number of attached project or location scopes.

ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "name",
        "message": "must be present"
      }
    ],
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}
Errors

Status codes

401invalid_api_key

The API key is absent or invalid.

403forbidden

The key lacks workspace analytics:write access.

404not_found

The token source was not found in this workspace.

422validation_failed | limit_reached

Input is invalid or the workspace limit was reached.

DELETE
/google_analytics_token_sources/{id}

Deletes an unused workspace token source.

Parameters

Path parameters

iduuid

Token source identifier.

Required
Response

Response body

deleted:true

Confirms deletion.

ErrorsResponse format and status codes
Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

Example error responseJSON
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "details": [
      {
        "field": "name",
        "message": "must be present"
      }
    ],
    "request_id": "req_01K1GP6J8QQFZ4D2B6C5A9V3TS"
  }
}
Errors

Status codes

401invalid_api_key

The API key is absent or invalid.

403forbidden

The key lacks workspace analytics:write access.

404not_found

The token source was not found in this workspace.

409token_source_in_use

Attached analytics scopes must be disconnected first.

422validation_failed | limit_reached

Input is invalid or the workspace limit was reached.