통합 상호작용 조회

매개변수

쿼리

이름	유형	필수	설명	기본값
tag	string	선택	Location tag to scope the rollup to. Defaults to `all`, every location the key can see. Omit it unless you tag locations.	all
siteUrls	string	선택	JSON-encoded array of publisher hostnames to include.	—
startDate	string	선택	Start of the date-range filter (YYYY-MM-DD).	—
endDate	string	선택	End of the date-range filter (YYYY-MM-DD).	—
searchString	string	선택	Full-text search across interaction content.	—
category	string	선택	Single interaction category, e.g. `REVIEW`.	—
categories	string	선택	JSON-encoded array of interaction categories.	—
ratingFilters	string	선택	JSON-encoded array of star ratings to include, e.g. `[3,4]`.	—
ratingFilter	integer	선택	Single star rating to filter by.	—
responseStatus	string	선택	JSON-encoded response-status filter. Values: `RESPONDED`, `PENDING`.	—
sortOrder	string	선택	JSON-encoded sort order. Values: `NEWEST_FIRST`, `OLDEST_FIRST`, `LAST_RESPONDED`.	—
first	integer	선택	Number of records to return from the beginning. Defaults to 20 when omitted, the endpoint always returns a single page, never the whole history.	—
after	string	선택	Cursor to page forward from. Pass `pageInfo.endCursor`, or equivalently the `cursor` of the last edge in the previous page.	—
last	integer	선택	Number of records to return from the end.	—
before	string	선택	Cursor to page backward from, used with `last`. Pass the `cursor` of the first edge of the page you are moving back from. `pageInfo` carries no `startCursor` field, so the edge cursor is the value to use.	—

응답

200Paginated rollup of interactions across the account. `data.rollupInteractions` holds the connection.

Response

{  "data": {    "rollupInteractions": {      "pageInfo": {        "hasNextPage": true,        "hasPreviousPage": false      },      "edges": [        {          "node": {            "id": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",            "source": "maps.google.com",            "content": "Excellent service, highly recommend.",            "authorName": "Priya S.",            "rating": 5,            "date": "2026-06-30T12:04:11+00:00",            "category": "Review",            "type": "Review",            "responded": false,            "responseCount": 0,            "canRespond": true,            "locationId": 1800289          },          "cursor": "SW50ZXJhY3Rpb246OWUyNmQyYTg="        }      ],      "totalCount": 1284    }  }}

401Unauthenticated, missing or invalid API key.

429Rate limit exceeded. Retry after the `Retry-After` header value.

계정 내 여러 사업장의 상호작용을 통합하여 반환합니다. 사업장별 상호작용 목록 조회 엔드포인트와 동일한 커서 기반 페이지네이션(first, last, after, before) 및 필터를 지원합니다. 연결은 data.rollupInteractions에 있으며, 각 node에는 locationId가 포함되어 있어 상호작용이 어느 사업장에 속하는지 확인할 수 있습니다.

totalCount는 범위에 포함된 모든 사업장에서 필터와 일치하는 상호작용 수이며, 이 페이지에서 반환된 수가 아닙니다. first를 생략하면 20개의 레코드가 반환되므로 한 번의 호출로는 계정의 전체 이력을 가져올 수 없으며, totalCount개의 레코드를 확보할 때까지 after로 페이지를 순회해야 합니다.

주의 사항: 통합 범위는 항상 계정 전체입니다

이 엔드포인트에는 사업장별 매개변수가 없습니다. 기본값인 tag=all을 사용하면 API 키로 조회할 수 있는 모든 사업장을 통합하며, 이보다 좁은 범위는 사업장 tag뿐입니다. locationFilters 또는 locationIds 인수는 없으며, 이를 전송해도 거부되지 않고 무시됩니다. 지원되는 필터(siteUrls, responseStatus, sortOrder, startDate/endDate, searchString)로 결과 집합을 좁히거나 각 노드의 locationId를 기준으로 결과를 직접 그룹화합니다.

사용 사례: 계정 전체의 "답글 필요" 대기열

모든 사업장에서 아직 사업주 답글을 기다리는 리뷰를 전부 조회하려면 GET /rollup_interactions?responseStatus=["PENDING"]&sortOrder=["NEWEST_FIRST"]&first=50을 호출한 다음, after = pageInfo.endCursor(마지막 에지의 cursor와 동일)로 페이지를 순회하고 hasNextPage가 false이거나 페이지에서 빈 edges 배열을 반환하면 중지합니다. 이렇게 하면 사업장을 하나씩 순회할 필요가 없습니다. 페이지네이션과 요청 빈도 제한이 적용되므로 429가 반환되면 Retry-After 헤더를 준수하고, 예약된 동기화에서는 날짜 범위(startDate/endDate)를 지정해 실행하는 것이 좋습니다.