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 (under Account) in the Remark dashboard.

Create a key

Click Create API key, enter a name, choose Expires on date or No expiry, and click Create key.

Copy the token

Copy the token immediately — it is only shown once. Token format: rmrk_u_ followed by 64 hexadecimal characters.

Using the API Key

All requests go to the GraphQL endpoint:

POST https://api.remark.ai/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. To revoke a key, open its menu on the Personal API keys page and click Revoke key. Revocation takes effect immediately, and requests with a revoked or expired key fail with Invalid or expired API key.

Example Request

curl -X POST https://api.remark.ai/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!
  $channels: [ConversationChannel!]
) {
  vendorById(vendorId: $vendorId) {
    conversationAggregateStatistics(start: $start, end: $end, channels: $channels) {
      # Chat volume
      numberOfChats
      numberOfAIChats
      numberOfHumanChats
      automationRate

      # Revenue & conversions
      totalValueOfConversionsAttributedToChat
      totalValueOfConversionsAttributedToHumanChat
      totalValueOfConversionsAttributedToAIChat
      numberOfConversionsAttributed
      conversionRateForChatters
      conversionRateForNonChatters
      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 }
      }
      chattiestExperts(first: 10, includeAiExperts: true) {
        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"`)
`channels`	`[ConversationChannel!]`	No	Limit stats to these channels: `Remark_Chat`, `Gorgias_Ticket`, `Zendesk_Ticket`, `Kustomer_Conversation`, `Freshdesk_Ticket`, `Gladly_Conversation`

Example Response

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

Field Reference

Field	Description
`numberOfChats`	Total conversations in period
`numberOfAIChats`	Conversations handled entirely by AI
`numberOfHumanChats`	Conversations involving a human expert, including those where the AI also took part
`automationRate`	Conversation segments handled entirely by AI, divided by all segments (0–1)
`totalValueOfConversionsAttributedToChat`	Total revenue attributed to chat interactions (USD)
`totalValueOfConversionsAttributedToHumanChat`	Revenue attributed to human-handled chats
`totalValueOfConversionsAttributedToAIChat`	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
`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. Ranges up to 3 days use `HOURLY` buckets, up to 31 days `DAILY`, under a year `WEEKLY`, and longer ranges `MONTHLY`
`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
`chattiestExperts`	Experts ranked by chat count. `includeAiExperts` controls whether AI personas are ranked
`topCitedKnowledge`	Most-referenced knowledge documents
`minutesSavedByRemark`	Estimated minutes saved by AI automation
`csatScore`	Share of positively rated conversations, from 0 to 1 (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
      totalValueOfConversionsAttributedToChat
      conversionRateForChatters
      aovForAttributedConversions
      automationRate
    }
    previous: conversationAggregateStatistics(start: $prevStart, end: $prevEnd) {
      numberOfChats
      totalValueOfConversionsAttributedToChat
      conversionRateForChatters
      aovForAttributedConversions
      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`	Yes	Page size, from 1 to 100
`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

A conversation must match every key inside a single ConversationFilterInput. When you pass several filter objects, a conversation matches if it satisfies any one of them.

Filter Key	Type	Description
`expertId`	`ID`	Filter by assigned expert
`email`	`String`	Search by customer email
`ipAddress`	`String`	Filter by shopper IP address
`conversionStatus`	`Enum`	`ATTRIBUTED`, `CONVERTED`, `UNATTRIBUTED`, `NONE`
`smartTagIds`	`[ID]`	Filter by smart tag IDs
`recommendedProductIds`	`[ID]`	Conversations that recommended any of these products
`npsRating`	`Enum`	`POSITIVE`, `NEGATIVE`
`sentiment`	`Enum`	AI-inferred sentiment: `POSITIVE`, `NEGATIVE`, `NEUTRAL`
`feedbackStatuses`	`[Enum]`	Message feedback: `POSITIVE`, `NEGATIVE`, or `NONE` for conversations without feedback
`expertChatType`	`Enum`	`AI`, `HUMAN`, `BOTH`, `HAS_AI`, `HAS_HUMAN`
`channels`	`[ConversationChannel]`	Filter by channel type (values listed under Dashboard Statistics)
`startSource`	`Enum`	How the conversation started: `CHAT`, `CHATLESS`, `QA_ACTIVATOR`, `LIVE_VIEW`
`hasEngagement`	`Boolean`	Whether the conversation counts as an engagement
`detectedIntentIds`	`[ID]`	Conversations where any of these intents was detected
`actionNames`	`[String]`	Conversations where any of these actions ran, formatted like `Remark.ACTION_NAME`
`createdAfter` / `createdBefore`	`DateTime`	Created on or after / on or before this date (inclusive)
`openedAfter` / `openedBefore`	`DateTime`	Started or reopened on or after / on or before this date (inclusive)

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`.

Only the first entry in sort is used. Without sort, results come back in an arbitrary but stable order.

For exports, backfills, and other long pagination jobs, explicitly sort by created. lastMessageDate changes when an older conversation receives a new message, which can 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 explanation intent { id name } }
          actionsTaken { actionName actionAlias actionSuccess }
          recommendations {
            product { id name }
            variant { id name }
          }
          knowledgeCitations {
            count
            citations { id title knowledgeDocument { id title } }
          }
        }
      }
    }
  }
}

Conversation Customer Events

Use customerEvent to fetch the browsing and shopping events from the most recent storefront session of the conversation’s shopper, newest first. Pass the conversation ID as id. The session can be a later visit than the chat itself. This is the right place to look for product views, category page views, searches, cart activity, and purchases.

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	`name` (page title), `created`
`Search`	Shopper searched the site	`search`
`CartAdd` / `CartRemove`	Shopper changed their cart	`product`, `cart`
`Purchase`	Shopper completed an order	`product`, `cart`
`UserLeave` / `UserReturn`	Shopper left or returned to the browser tab	`created`

Session & Order Data

Look up browsing sessions and conversion/order details for a customer. Pass the shopper’s tracker ID as lead. You can read it from a conversation as customerIdentity { lead }.

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: `Session`, `Email`, `Ip`, `SEOPageView`, or `LiveView`
`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