GraphQL API

Enterprise customers can use User API Keys to programmatically query their Remark data via the GraphQL API. This covers dashboard statistics, conversation history, smart tags, order data, and more.

Authentication

Create and use API keys to authenticate requests.

Dashboard Statistics

Query chat volume, revenue, conversion rates, and leaderboards.

Conversations

List conversations, fetch details, and inspect associated customer events.

Smart Tags

Aggregate smart tag counts across conversations.

Authentication

Creating an API Key

Navigate to API Keys

Go to Settings > Personal API Keys in the Remark dashboard.

Create a key

Click Create API Key, give it a name and optional expiry date.

Copy the token

Copy the token immediately — it is only shown once. Token format: rmrk_u_ followed by a secure hash.

Using the API Key

All requests go to the GraphQL endpoint:

POST https://api.withremark.com/graphql

Include your token in the Authorization header:

Authorization: Bearer rmrk_u_your_token_here

The key inherits the full permissions of the user who created it. Keys can be revoked at any time from the dashboard.

Example Request

curl -X POST https://api.withremark.com/graphql \
  -H "Authorization: Bearer rmrk_u_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "{ vendorById(vendorId: \"your-vendor-id\") { name } }"
  }'

Dashboard Statistics

The main analytics entry point. All stats are nested under vendorById > conversationAggregateStatistics and support filtering by date range and optionally by channel.

Permission required: VIEW_CONVERSIONS (for revenue/conversion fields)

All-in-One Dashboard Query

Fetches the most commonly used KPIs in a single request:

query DashboardStats(
  $vendorId: ID!
  $start: DateTime!
  $end: DateTime!
  $timezone: String!
  $channel: ConversationChannel
) {
  vendorById(vendorId: $vendorId) {
    conversationAggregateStatistics(start: $start, end: $end, channel: $channel) {
      # Chat volume
      numberOfChats
      numberOfAIChats
      numberOfHumanChats
      automationRate

      # Revenue & conversions
      totalValueOfConversationsAttributedToChat
      totalValueOfConversationsAttributedToHumanChat
      totalValueOfConversationsAttributedToAIChat
      numberOfConversionsAttributed
      conversionRateForChatters
      conversionRateForNonChatters
      aovForChatters
      aovForNonChatters
      aovForAttributedConversions
      aovForNonAttributedConversions

      # Performance
      averageExpertResponseTime
      medianJoinTime
      totalManHoursSpentInChat

      # Time series
      attributedRevenueTimeSeries(timezone: $timezone) {
        precision
        time
        totalAttributedValue
      }
      chatsByHourHistogram(timezone: $timezone) {
        hour
        count
        average
      }
      chatsByDayOfWeekHistogram(timezone: $timezone) {
        day
        dayIndex
        chatCount
        dayCount
      }

      # Leaderboards
      topProductsByAttributedSales {
        numberOfRecommendations
        numberSold
        totalSales
        product { id name }
      }
      topExpertByAttributedSales {
        asAiPersona
        attributedAmountUSD
        expert { id firstName lastName }
      }
      topExperts(first: 10) {
        asAiPersona
        numberOfChats
        isCSAgent
        expert { id firstName lastName }
      }
      topCitedKnowledge {
        count
        knowledgeDocument { id title }
      }

      # Impact
      minutesSavedByRemark

      # CSAT (requires VIEW_NPS)
      csatScore
    }
  }
}

Variables

Variable	Type	Required	Description
`vendorId`	`ID!`	Yes	Your vendor ID
`start`	`DateTime!`	Yes	Period start (ISO 8601)
`end`	`DateTime!`	Yes	Period end (ISO 8601)
`timezone`	`String!`	Yes	IANA timezone for time series (e.g. `"America/New_York"`)
`channel`	`ConversationChannel`	No	Filter by channel: `RemarkChat`, `GorgiasTicket`, `ZendeskTicket`, `KustomerConversation`

Example Response

{
  "data": {
    "vendorById": {
      "conversationAggregateStatistics": {
        "numberOfChats": 1842,
        "numberOfAIChats": 1455,
        "numberOfHumanChats": 387,
        "automationRate": 0.79,
        "totalValueOfConversationsAttributedToChat": 284500.00,
        "numberOfConversionsAttributed": 156,
        "conversionRateForChatters": 0.085,
        "conversionRateForNonChatters": 0.032,
        "aovForChatters": 185.50,
        "aovForNonChatters": 142.00,
        "averageExpertResponseTime": 45,
        "medianJoinTime": 12,
        "attributedRevenueTimeSeries": [
          { "precision": "DAY", "time": "2026-03-01T00:00:00Z", "totalAttributedValue": 9500.00 },
          { "precision": "DAY", "time": "2026-03-02T00:00:00Z", "totalAttributedValue": 11200.00 }
        ],
        "topProductsByAttributedSales": [
          {
            "numberOfRecommendations": 89,
            "numberSold": 34,
            "totalSales": 6120.00,
            "product": { "id": "prod_1", "name": "Trail Runner Pro" }
          }
        ],
        "minutesSavedByRemark": 48500,
        "csatScore": 4.6
      }
    }
  }
}

Field Reference

Field	Description
`numberOfChats`	Total conversations in period
`numberOfAIChats`	Conversations handled entirely by AI
`numberOfHumanChats`	Conversations involving a human expert
`automationRate`	Fraction of chats handled by AI (0–1)
`totalValueOfConversationsAttributedToChat`	Total revenue attributed to chat interactions (USD)
`totalValueOfConversationsAttributedToHumanChat`	Revenue attributed to human-handled chats
`totalValueOfConversationsAttributedToAIChat`	Revenue attributed to AI-handled chats
`numberOfConversionsAttributed`	Number of orders attributed to chat
`conversionRateForChatters`	Conversion rate for visitors who chatted
`conversionRateForNonChatters`	Conversion rate for visitors who did not chat
`aovForChatters`	Average order value for chatters (USD)
`aovForNonChatters`	Average order value for non-chatters (USD)
`aovForAttributedConversions`	AOV for orders directly attributed to chat
`aovForNonAttributedConversions`	AOV for non-attributed orders
`averageExpertResponseTime`	Average expert response time (seconds)
`medianJoinTime`	Median time for an expert to join a chat (seconds)
`totalManHoursSpentInChat`	Total expert hours spent in chat
`attributedRevenueTimeSeries`	Revenue over time, bucketed by day/week/month
`chatsByHourHistogram`	Chat volume by hour of day
`chatsByDayOfWeekHistogram`	Chat volume by day of week
`topProductsByAttributedSales`	Products ranked by attributed revenue
`topExpertByAttributedSales`	Single top expert by revenue
`topExperts`	Experts ranked by chat count
`topCitedKnowledge`	Most-referenced knowledge documents
`minutesSavedByRemark`	Estimated minutes saved by AI automation
`csatScore`	Average CSAT score (requires VIEW_NPS)

Period-over-Period Comparison

Use GraphQL aliases to fetch current and previous periods in one request:

query DashboardComparison(
  $vendorId: ID!
  $start: DateTime!
  $end: DateTime!
  $prevStart: DateTime!
  $prevEnd: DateTime!
) {
  vendorById(vendorId: $vendorId) {
    current: conversationAggregateStatistics(start: $start, end: $end) {
      numberOfChats
      totalValueOfConversationsAttributedToChat
      conversionRateForChatters
      aovForChatters
      automationRate
    }
    previous: conversationAggregateStatistics(start: $prevStart, end: $prevEnd) {
      numberOfChats
      totalValueOfConversationsAttributedToChat
      conversionRateForChatters
      aovForChatters
      automationRate
    }
  }
}

Smart Tag Aggregation

Count how often each smart tag was applied to conversations in a time range. Useful for tracking trending topics, common customer issues, or product interest over time.

Permission required: VIEW_CONVERSATIONS

Count Tags in a Period

query SmartTagSummary($vendorId: ID!, $start: DateTime!, $end: DateTime!) {
  smartTagCounts(vendorId: $vendorId, start: $start, end: $end) {
    tag {
      id
      title
      description
    }
    count
  }
}

Example Response

{
  "data": {
    "smartTagCounts": [
      {
        "tag": { "id": "tag_1", "title": "Sizing Question", "description": "Customer asked about product sizing" },
        "count": 234
      },
      {
        "tag": { "id": "tag_2", "title": "Return Request", "description": "Customer wants to return a product" },
        "count": 89
      }
    ]
  }
}

List Available Smart Tags

query VendorTags($vendorId: ID!) {
  vendorSmartTags(vendorId: $vendorId) {
    id
    title
    description
  }
}

Conversation Listing

Paginated list of conversations with filtering and sorting. Uses cursor-based pagination.

Permission required: VIEW_CONVERSATIONS

query Conversations(
  $vendorId: ID!
  $first: Int
  $cursor: ID
  $sort: [ConversationSortInput!]
  $filter: [ConversationFilterInput!]
) {
  conversations(
    vendorId: $vendorId
    first: $first
    cursor: $cursor
    sort: $sort
    filter: $filter
  ) {
    edges {
      cursor
      node {
        id
        status
        channel
        platform
        subject
        created
        lastMessageDate
        updated
        customerIdentity {
          id
          suppliedFirstName
          email           # requires VIEW_PII
        }
        currentExpert {
          id
          firstName
          lastName
        }
        hasAttributedConversion(anyExpert: true)
        hasPositiveNPS(anyExpert: true)
        vendorConversationSummaries {
          summary
        }
        mostRecentSegmentStats {
          smartTags { id title }
          aiAppliedTags { tag weight explanation }
          aiInferredSentiment
          pairingTime
          totalTimeSpentChatting
        }
      }
    }
    totalCount
    hasNextPage
    hasPrevPage
    startCursor
    endCursor
  }
}

Variables

Variable	Type	Required	Description
`vendorId`	`ID!`	Yes	Your vendor ID
`first`	`Int`	No	Page size (default varies)
`cursor`	`ID`	No	Cursor from previous page’s `endCursor`
`sort`	`[ConversationSortInput!]`	No	Sort criteria. For stable pagination, pass `[{ field: created, direction: desc }]`.
`filter`	`[ConversationFilterInput!]`	No	Filter criteria

Filter Key	Type	Description
`expertId`	`ID`	Filter by assigned expert
`email`	`String`	Search by customer email
`conversionStatus`	`Enum`	`Attributed`, `Converted`, `None`
`smartTagIds`	`[ID]`	Filter by smart tag IDs
`npsRating`	`Enum`	`Positive`, `Negative`
`sentiment`	`Enum`	AI-inferred sentiment
`expertChatType`	`Enum`	`AI`, `Human`, `Both`, `HasAI`, `HasHuman`
`channels`	`[ConversationChannel]`	Filter by channel type

Sort Options

Field	Direction
`created`	`desc` (newest conversation first) or `asc`. Recommended for paginating long result sets.
`lastMessageDate`	`desc` (most recently active first) or `asc`. Used when no sort is supplied.

For exports, backfills, and other long pagination jobs, explicitly sort by created. The default sort is lastMessageDate, which can change when an older conversation receives a new message and may make cursor pagination less stable over time.

Recommended Variables

{
  "vendorId": "your-vendor-id",
  "first": 50,
  "sort": [{ "field": "created", "direction": "desc" }]
}

Pagination

Use cursor-based pagination to iterate through results:

# First page
conversations(
  vendorId: "..."
  first: 50
  sort: [{ field: created, direction: desc }]
) { ... }

# Next page
conversations(
  vendorId: "..."
  first: 50
  cursor: "endCursor_from_previous"
  sort: [{ field: created, direction: desc }]
) { ... }

Conversation Detail

Fetch a single conversation with its full message history.

Permission required: VIEW_CONVERSATIONS

query ConversationDetail($id: ID!, $last: Int!) {
  conversation(id: $id) {
    id
    channel
    platform
    subject
    status
    created
    updated
    externalUrl
    customerIdentity {
      id
      suppliedFirstName
      email               # requires VIEW_PII
      location
    }
    hasAttributedConversion(anyExpert: true)
    hasPositiveNPS(anyExpert: true)
    vendorConversationSummaries { summary }
    npsSurveys {                          # requires VIEW_NPS
      id
      rating
      expert { id firstName lastName }
    }
    mostRecentSegmentStats {
      smartTags { id title description }
      aiAppliedTags { tag weight explanation }
      aiInferredSentiment
      pairingTime
      totalTimeSpentChatting
    }
    events(last: $last) {
      totalCount
      hasNextPage
      hasPrevPage
      endCursor
      startCursor
      edges {
        cursor
        node {
          id
          body
          type
          created
          expert { id firstName lastName }
          detectedIntents { id name explanation }
          actionsTaken { name success }
          recommendations {
            product { id name }
            variant { id name }
          }
          knowledgeCitations {
            knowledgeDocument { id title }
          }
        }
      }
    }
  }
}

Conversation Customer Events

Use customerEvent to fetch the browsing and shopping events associated with a conversation’s session. This is the right place to look for product views, category page views, searches, and cart activity that happened around a chat.

Permission required: VIEW_CONVERSATIONS

query ConversationCustomerEvents($conversationId: ID!, $vendorId: ID!) {
  customerEvent(id: $conversationId, vendorId: $vendorId) {
    id
    created
    type
    name
    search
    product {
      id
      externalId
      name
      brandName
      externalUrl
    }
    cart {
      id
    }
  }
}

Event Types

Type	Meaning	Useful fields
`ProductPageView`	Shopper viewed a product detail page	`product.id`, `product.externalId`, `product.name`, `product.brandName`, `product.externalUrl`
`CategoryPageView`	Shopper viewed a category or collection page	`name`
`PageView`	Shopper viewed a non-product page	`created`, `type`
`Search`	Shopper searched the site	`search`
`CartAdd` / `CartRemove`	Shopper changed their cart	`product`, `cart`

Session & Order Data

Look up browsing sessions and conversion/order details for a customer.

Permission required: VIEW_CONVERSIONS

query SessionDetails($vendorId: ID!, $lead: String!) {
  sessionByVendorId(vendorId: $vendorId, lead: $lead) {
    id
    lastUserAgent {
      browser
      deviceType
      deviceModel
    }
    conversions(last: 10) {
      edges {
        node {
          id
          created
          totalPrice
          currency
          orderNumber
          externalId
          externalUrl
          platform
          attributionMethod
          lineItems {
            quantity
            finalTotalPrice
            product { id name }
            variant { id name }
          }
          attribution {
            method
            chattingExpert { id firstName lastName }
          }
        }
      }
    }
  }
}

Key Fields

Field	Description
`totalPrice`	Order total
`attributionMethod`	How the conversion was attributed to chat
`attribution.chattingExpert`	The expert credited with the sale
`lineItems`	Individual products/variants in the order

Permissions Reference

Your API key inherits the permissions of the user who created it. Different data requires different permissions:

Permission	Grants access to
VIEW_CONVERSATIONS	Conversation data, smart tags, message history, chat analysis
VIEW_CONVERSIONS	Revenue metrics, conversion rates, order details, attributed sales
VIEW_PII	Customer emails, names, IP addresses, contact info
VIEW_NPS	NPS/CSAT scores and survey details
VIEW_BILLING	Billing and payment data
EDIT_ANALYTICS	Smart tag management (create/edit/delete)

An admin or vendor owner will have all permissions for their vendor.

Rate Limits & Best Practices

Rate limiting: Rate limits may be enforced to prevent abuse and maintain quality of service
Request only what you need: GraphQL lets you select specific fields — smaller queries are faster
Use pagination: Always paginate conversation and session lists rather than fetching everything at once
Cache where appropriate: Dashboard statistics don’t change in real time; polling every few minutes is sufficient
Time ranges: Always provide start/end for dashboard stats queries — omitting them returns lifetime data which is slower
Timezone: Pass your local IANA timezone (e.g. America/New_York) for time series and histogram queries to get correctly bucketed data

Getting Started

Guides

Dashboard

API

Integrations

Authentication

Dashboard Statistics

Conversations

Smart Tags

Authentication

Creating an API Key

Using the API Key

Example Request

Dashboard Statistics

All-in-One Dashboard Query

Variables

Example Response

Period-over-Period Comparison

Smart Tag Aggregation

Count Tags in a Period

Example Response

List Available Smart Tags

Conversation Listing

Variables

Sort Options

Recommended Variables

Conversation Detail

Conversation Customer Events

Event Types

Session & Order Data

Key Fields

Permissions Reference

Rate Limits & Best Practices

Authentication

Dashboard Statistics

Conversations

Smart Tags

​Authentication

​Creating an API Key

​Using the API Key

​Example Request

​Dashboard Statistics

​All-in-One Dashboard Query

​Variables

​Example Response

​Period-over-Period Comparison

​Smart Tag Aggregation

​Count Tags in a Period

​Example Response

​List Available Smart Tags

​Conversation Listing

​Variables

​Filter Options

​Sort Options

​Recommended Variables

​Pagination

​Conversation Detail

​Conversation Customer Events

​Event Types

​Session & Order Data

​Key Fields

​Permissions Reference

​Rate Limits & Best Practices

Authentication

Creating an API Key

Using the API Key

Example Request

Dashboard Statistics

All-in-One Dashboard Query

Variables

Example Response

Period-over-Period Comparison

Smart Tag Aggregation

Count Tags in a Period

Example Response

List Available Smart Tags

Conversation Listing

Variables

Filter Options

Sort Options

Recommended Variables

Pagination

Conversation Detail

Conversation Customer Events

Event Types

Session & Order Data

Key Fields

Permissions Reference

Rate Limits & Best Practices