Skip to main content

GraphQL Queries for AnnounceKit (Part 1)

What Can GraphQL Queries do for AnnounceKit?

GraphQL Queries are special commands for you to run in our IDE. These special commands are used to bring information about your project, such as your user_id, project_id and various of detailed information from your project.

How to use these queries?

Below is a documentation for all of the queries found in AnnounceKit, along with its explanations objects and arguments. Arguments are subfields for queries, and while some arguments among queries are optional, make sure to complete the required arguments as without them, you cannot run the queries.

Each of these queries below are used by going into our IDE located here.

We recommend that you get your project and user ID by running the query below.

{

me {

id

active_project {

id

}

}

}

You can also click on the link here to run this query.

me

Query:

The me query returns the current user. The me query does not take any arguments.

Object:

The User object is the data structure that is returned by the me query. It contains the following properties:

  • id: The unique identifier for the user.

  • hash: The hashed password for the user.

  • email: The email address for the user.

  • display_name: The display name for the user.

  • title: The title for the user.

  • created_at: The date and time the user was created.

  • image_id: The ID of the user's image.

  • image: The user's image.

  • active_project: The user's active project.

  • memberships: The user's memberships in projects.

  • avatar: The user's avatar.

  • is_validated: Whether the user has validated their email address.

  • is_totp_enabled: Whether the user has enabled two-factor authentication.

  • is_unsubs: Whether the user has unsubscribed from email notifications.

Examples:

The following example shows how to use the me query to get the current user's ID and name:

GraphQL

query {
  me {
    id
    display_name
  }
}

JSON

{
  "me": {
    "id": "123456789",
    "display_name": "John Doe"
  }
}

project

Query:

The project query returns a project by its ID. The project_id argument is the unique identifier for the project.

Argument:

The project_id argument is a required argument. It is the unique identifier for the project that you want to retrieve.

Object:

The Project object is the data structure that is returned by the project query. It contains the following properties:

  • id: The unique identifier for the project.

  • encodedId: The encoded ID for the project.

  • name: The name of the project.

  • slug: The slug of the project.

  • website: The website of the project.

  • is_authors_listed: Whether the authors of the project are listed.

  • is_whitelabel: Whether the project is whitelabeled.

  • is_subscribable: Whether the project is subscribable.

  • is_slack_subscribable: Whether the project is slack subscribable.

  • is_feedback_enabled: Whether feedback is enabled for the project.

  • is_demo: Whether the project is a demo project.

  • is_readonly: Whether the project is readonly.

  • image_id: The ID of the project's image.

  • favicon_id: The ID of the project's favicon.

  • image: The project's image.

  • created_at: The date and time the project was created.

  • ga_property: The Google Analytics property for the project.

  • privacy_policy_url: The privacy policy URL for the project.

  • members: The members of the project.

  • invites: The invites to the project.

  • labels: The labels for the project.

  • statuses: The statuses for the project.

  • billing_info: The billing information for the project.

  • subscription: The subscription for the project.

  • avatar: The avatar for the project.

  • favicon: The favicon for the project.

  • plan: The plan for the project.

  • locale: The locale for the project.

  • locales: The locales for the project.

  • feeds: The feeds for the project.

  • integrations: The integrations for the project.

  • analytics: The analytics for the project.

  • usesNewFeedHostname: Whether the project uses the new feed hostname.

  • payment_gateway: The payment gateway for the project.

  • trial_until: The trial end date for the project.

  • metadata: The metadata for the project.

  • widget: The widget for the project.

Examples:

The following example shows how to use the project query to get a project by its ID:

GraphQL

query {
  project(project_id: "123456789") {
    id
    name
    slug
  }
}

The following JSON shows the response that would be returned by the GraphQL server:

JSON

{
  "project": {
    "id": "123456789",
    "name": "My Project",
    "slug": "my-project"
  }
}

post

Query

The post query is a GraphQL query that returns information about a post. The query takes two arguments:

  • project_id (required): The ID of the project that the post belongs to.

  • post_id (required): The ID of the post.

Object

  • Post: The Post object that is returned by the post query.

    • id: The unique identifier for the post.

    • project_id: The ID of the project that the post belongs to.

    • user_id: The ID of the user who created the post.

    • project: The Project object that the post belongs to.

    • user: The User object who created the post.

    • created_at: The date and time the post was created.

    • visible_at: The date and time the post will be visible to everyone.

    • image_id: The ID of the image for the post.

    • expire_at: The date and time the post will expire.

    • updated_at: The date and time the post was last updated.

    • is_draft: Whether the post is a draft.

    • is_pushed: Whether the post has been pushed to production.

    • is_pinned: Whether the post is pinned to the top of the project.

    • is_internal: Whether the post is internal only.

    • external_url: The external URL for the post.

    • labels: The labels for the post.

    • segment_filters: The segment filters for the post.

    • flags: The flags for the post.

    • defaultContent: The default content for the post.

    • contents: The contents of the post.

    • view_data: The view data for the post.

    • status: The status of the post.

    • is_paused: Whether the post is paused.

    • notification: The notification for the post.

Examples

The following query will return the post with the ID 123456789 in the project with the ID 123456789:

GraphQL

{
  post(project_id: 123456789, post_id: 123456789) {
    id
    created_at
  }
}

This query will return the following JSON:

JSON

{
  "post": {
    "id": "123456789",
    "created_at": "2023-07-13T11:11:11Z"
  }
}

posts

Query

The posts query is a GraphQL query that returns a list of posts. The query takes the following arguments:

  • project_id (required): The ID of the project that the posts belong to.

  • page (optional): The page number of the results to return. Defaults to 0.

  • labels (optional): A list of IDs of the labels that the posts should have.

  • query (optional): A search query for the posts.

  • createdBy (optional): The ID of the user who created the posts.

  • postStatus (optional): The status of the posts.

  • orderField (optional): The field to order the posts by.

Object

  • Posts: The Posts object that is returned by the posts query.

    • list: A list of Post objects.

    • count: The total number of posts.

    • page: The current page number.

    • pages: The total number of pages.

Examples

The following query will return the first page of posts in the project with the ID 123456789:

GraphQL

{
  posts(project_id: 123456789) {
    list {
      id
      created_at
    }
    count
    page
    pages
  }
}

JSON

{
  "posts": {
    "list": [
      {
        "id": "123456789",
        "created_at": "2023-07-13T11:11:11Z"
      }
    ],
    "count": 100,
    "page": 1,
    "pages": 10
  }
}

postTemplates

Query

The postTemplates query is a GraphQL query that returns a list of post templates. The query takes the following argument:

  • project_id (required): The ID of the project that the post templates belong to.

Object

  • PostTemplate: The PostTemplate object that is returned by the postTemplates query.

    • id: The unique identifier for the post template.

    • title: The title of the post template.

    • body: The body of the post template.

Examples

The following query will return all of the post templates in the project with the ID 123456789:

GraphQL

{
  postTemplates(project_id: 123456789) {
    id
    title
    body
  }
}

This query will return the following JSON:

JSON

{
  "postTemplates": [
    {
      "id": "123456789",
      "title": "My Post Template",
      "body": "This is the body of my post template."
    },
    {
      "id": "987654321",
      "title": "Another Post Template",
      "body": "This is the body of another post template."
    }
  ]
}

feedbackCounts

Query

The feedbackCounts query is a GraphQL query that returns a list of feedback counts for a post. The query takes the following arguments:

  • project_id (required): The ID of the project that the post belongs to.

  • post_id (optional): The ID of the post.

Object

  • FeedbackCount: The FeedbackCount object that is returned by the feedbackCounts query.

    • reaction: The reaction type.

    • count: The number of feedbacks for the reaction type.

Examples

The following query will return the feedback counts for the post with the ID 123456789 in the project with the ID 123456789:

GraphQL

{
  feedbackCounts(project_id: 123456789, post_id: 123456789) {
    reaction
    count
  }
}

This query will return the following JSON:

JSON

{
  "feedbackCounts": [
    {
      "reaction": ":)",
      "count": 100
    },
    {
      "reaction": ":(",
      "count": 50
    },
    {
      "reaction": ":)",
      "count": 25
    }
  ]
}

feedbackHappinessTable

Query

The feedbackHappinessTable query is a GraphQL query that returns a table of feedback happiness scores for a post. The query takes the following arguments:

  • project_id (required): The ID of the project that the post belongs to.

  • post_id (optional): The ID of the post.

Object

The Float scalar type represents signed double-precision fractional values as specified by IEEE 754.

Examples

The following query will return the feedback happiness table for the post with the ID 123456789 in the project with the ID 123456789:

GraphQL

{
  feedbackHappinessTable(project_id:123456789,post_id:123456789) 
}

This query will return the following JSON:

JSON

{
  "data": {
    "feedbackHappinessTable": [
      [
        1688947200000,
        0.75
      ]
    ]
  }
}

feedbacks

Query

The feedbacks query is a GraphQL query that returns a paginated list of feedbacks for a post. The query takes the following arguments:

  • project_id (required): The ID of the project that the post belongs to.

  • post_id (required): The ID of the post.

  • page (optional): The page number of the results to return. Defaults to 0.

Object

The PageOfFeedback object that is returned by the feedbacks query is a paginated list of feedbacks. The object has the following properties:

  • page (integer): The current page number.

  • pages (integer): The total number of pages.

  • count (integer): The total number of feedbacks.

  • items (array of Feedback objects): The list of feedbacks on the current page.

Examples

The following query will return the first page of feedbacks for the post with the ID 123456789 in the project with the ID 123456789:

GraphQL

{
  feedbacks(project_id: 123456789, post_id: 123456789) {
    page
    pages
    count
    items {
      reaction
      feedback
    }
  }
}

This query will return the following JSON:

JSON

{
  "data": {
    "feedbacks": {
      "page": 0,
      "pages": 1,
      "count": 6,
      "items": [
        {
          "reaction": ":)",
          "feedback": null
        },
        {
          "reaction": null,
          "feedback": "test"
        },
        {
          "reaction": ":)",
          "feedback": null
        },
        {
          "reaction": ":)",
          "feedback": null
        },
        {
          "reaction": ":)",
          "feedback": null
        },
        {
          "reaction": ":)",
          "feedback": null
        }
      ]
    }
  }
}

activities

Query

The activities query is a GraphQL query that returns a paginated list of activities for a post. The query takes the following arguments:

  • project_id (required): The ID of the project that the post belongs to.

  • post_id (optional): The ID of the post.

  • external_user_id (optional): The ID of the external user who performed the activities.

  • page (optional): The page number of the results to return. Defaults to 0.

  • type (optional): A list of activity types.

  • segmentProfile (optional): A JSON object that represents the segment profile of the user who performed the activities.

Object

The PageOfActivities object that is returned by the activities query is a paginated list of activities. The object has the following properties:

  • items (array of Activity objects): The list of activities on the current page.

  • page (integer): The current page number.

  • pages (integer): The total number of pages.

  • count (integer): The total number of activities.

Examples

The following query will return the first page of activities for the post with the ID 123456789 in the project with the ID 123456789 for the post with the ID 123456789:

GraphQL

{
  activities(project_id: 123456789, post_id: 123456789) {
    items {
      id
      type
    }
    page
    pages
    count
  }
}

This query will return the following JSON:

JSON

{
  "data": {
    "activities": {
      "items": [
        {
          "id": "123456789",
          "type": "mail-read"
        },
        {
          "id": "123456789",
          "type": "mail-read"
        },
        {
          "id": "123456789",
          "type": "mail-read"
        },
        {
          "id": "123456789",
          "type": "mail-read"
        },
        {
          "id": "123456789",
          "type": "mail-read"
        },
        {
          "id": "123456789",
          "type": "mail-read"
        },
        {
          "id": "123456789",
          "type": "mail-read"
        },
        {
          "id": "123456789",
          "type": "mail-link-click"
        },
        {
          "id": "123456789",
          "type": "mail-read"
        },
        {
          "id": "123456789",
          "type": "mail-read"
        }
      ],
      "page": 0,
      "pages": 240,
      "count": 2399
    }
  }
}

unreadActivities

Query

The unreadActivities query is a GraphQL query that returns the number of unread activities for a project. The query takes the following argument:

  • project_id (required): The ID of the project.

Object

The UnreadActivities object that is returned by the unreadActivities query is a object with the following properties:

  • id (integer): The ID of the project.

  • count (integer): The number of unread activities.

Examples

The following query will return the number of unread activities for the project with the ID 123456789:

GraphQL

{
  unreadActivities(project_id:123456789) {
    id
    count
  }
}

This query will return the following JSON:

JSON

{
  "data": {
    "unreadActivities": {
      "id": "123456789",
      "count": 27
    }
  }
}

checkEmailDigest

Query

The checkEmailDigest query is a GraphQL query that returns the status of email digests for a project. The query takes the following argument:

  • project_id (required): The ID of the project.

Object

The EmailDigestStatus object that is returned by the checkEmailDigest query is a object with the following properties:

  • id (integer): The ID of the project.

  • sending_interval (string): The interval at which email digests are sent.

Examples

The following query will return the status of email digests for the project with the ID 123456789:

GraphQL

{
  checkEmailDigest(project_id:123456789) {
    id
  }
}

This query will return the following JSON:

JSON

{
  "checkEmailDigest": {
    "id": "123456789",
    "sending_interval": "weekly"
  }
}

auditlog

Query

The auditlog query is a GraphQL query that returns a paginated list of audit logs for a project. The query takes the following arguments:

  • project_id (required): The ID of the project.

  • page (optional): The page number of the results to return. Defaults to 0.

Argument

  • project_id: The ID of the project.

    • This argument is required.

    • The ID must be a valid integer.

  • page: The page number of the results to return.

    • This argument is optional.

    • The default value is 0.

Object

The PageOfAuditlog object that is returned by the auditlog query is a paginated list of audit logs. The object has the following properties:

  • items (array of Auditlog objects): The list of audit logs on the current page.

  • page (integer): The current page number.

  • pages (integer): The total number of pages.

  • count (integer): The total number of audit logs.

Object

The Auditlog object that is returned by the auditlog query is a object with the following properties:

  • id (integer): The ID of the audit log.

  • created_at (string): The date and time the audit log was created.

  • username (string): The username of the user who performed the action.

  • ip_address (string): The IP address of the user who performed the action.

  • event_type (string): The type of event that was logged.

  • event_action (string): The action that was performed.

  • metadata (JSON object): A JSON object that contains additional metadata about the audit log.

Examples

The following query will return the first page of audit logs for the project with the ID 123456789:

GraphQL

{
  auditlog(project_id: 123456789) {
    items {
      id
      created_at
      username
      ip_address
      event_type
      event_action
      metadata
    }
    page
    pages
    count
  }
}

This query will return the following JSON:

JSON

{
  "auditlog": {
    "items": [
      {
        "id": "123456789",
        "created_at": "2023-07-13T11:11:11Z",
        "username": "John Doe",
        "ip_address": "192.168.1.1",
        "event_type": "post_created",
        "event_action": "created",
        "metadata": {
          "post_id": "123456789"
        }
      },
      {
        "id": "987654321",
        "created_at": "2023-07-13T11:11:12Z",
        "username": "Jane Doe",
        "ip_address": "192.168.1.2",
        "event_type": "comment_created",
        "event_action": "created",
        "metadata": {
          "post_id": "123456789",
          "comment_id": "987654321"
        }
      }
    ],
    "page": 1,
    "pages": 10,
    "count": 100
  }
}

feed

The feed query is a GraphQL query that returns a feed. The query takes the following arguments:

  • project_id (required): The ID of the project that the feed belongs to.

  • feed_id (required): The ID of the feed.
    ​
    ​Note project_id and feed_id are usually the same

Argument

  • project_id: The ID of the project that the feed belongs to.

    • This argument is required.

    • The ID must be a valid integer.

  • feed_id: The ID of the feed.

    • This argument is required.

    • The ID must be a valid integer.

Object

The Feed object that is returned by the feed query is a object with the following properties:

  • id (integer): The ID of the feed.

  • project_id (integer): The ID of the project that the feed belongs to.

  • project (object): The project that the feed belongs to.

  • name (string): The name of the feed.

  • slug (string): The slug of the feed.

  • created_at (string): The date and time the feed was created.

  • custom_host (string): The custom host for the feed.

  • website (string): The website for the feed.

  • color (string): The color of the feed.

  • url (string): The URL of the feed.

  • is_disabled (boolean): Whether the feed is disabled.

  • is_unindexed (boolean): Whether the feed is unindexed.

  • is_private (boolean): Whether the feed is private.

  • is_readmore (boolean): Whether the feed has readmore enabled.

  • html_inject (string): The HTML inject for the feed.

  • metadata (JSON object): A JSON object that contains additional metadata about the feed.

  • theme (JSON object): A JSON object that contains the theme for the feed.

  • version (integer): The version of the feed.

Examples

The following query will return the feed with the ID 123456789 in the project with the ID 123456789:

GraphQL

{
  feed(project_id: 123456789, feed_id: 123456789) {
    id
    project_id
    name
    slug
    created_at
    custom_host
    website
    color
    url
    is_disabled
    is_unindexed
    is_private
    is_readmore
    html_inject
    metadata
    theme
    version
  }
}

This query will return the following JSON:

JSON

{
  "feed": {
    "id": "123456789",
    "project_id": "123456789",
    "name": "My Feed",
    "slug": "my-feed",
    "created_at": "2023-07-13T11:11:11Z",
    "custom_host": null,
    "website": null,
    "color": "#ffffff",
    "url": "https://my-feed.com/",
    "is_disabled": false,
    "is_unindexed": false,
    "is_private": false,
    "is_readmore": true,
    "html_inject": null,
    "metadata": {},
    "theme": {},
    "version": 1
  }
}

feeds

Query

The feeds query is a GraphQL query that returns a list of feeds. The query takes the following arguments:

  • project_id (required): The ID of the project that the feeds belong to.

Argument

  • project_id: The ID of the project that the feeds belong to.

    • This argument is required.

    • The ID must be a valid integer.

Object

The Feed object that is returned by the feeds query is a object with the following properties:

  • id (integer): The ID of the feed.

  • project_id (integer): The ID of the project that the feed belongs to.

  • project (object): The project that the feed belongs to.

  • name (string): The name of the feed.

  • slug (string): The slug of the feed.

  • created_at (string): The date and time the feed was created.

  • custom_host (string): The custom host for the feed.

  • website (string): The website for the feed.

  • color (string): The color of the feed.

  • url (string): The URL of the feed.

  • is_disabled (boolean): Whether the feed is disabled.

  • is_unindexed (boolean): Whether the feed is unindexed.

  • is_private (boolean): Whether the feed is private.

  • is_readmore (boolean): Whether the feed has readmore enabled.

  • html_inject (string): The HTML inject for the feed.

  • metadata (JSON object): A JSON object that contains additional metadata about the feed.

  • theme (JSON object): A JSON object that contains the theme for the feed.

  • version (integer): The version of the feed.

Examples

The following query will return all of the feeds in the project with the ID 123456789:

GraphQL

{
  feeds(project_id: 123456789) {
    id
    project_id
    name
    slug
    created_at
    custom_host
    website
    color
    url
    is_disabled
    is_unindexed
    is_private
    is_readmore
    html_inject
    metadata
    theme
    version
  }
}

This query will return the following JSON:
​

JSON

{
  "feeds": [
    {
      "id": "123456789",
      "project_id": "123456789",
      "name": "My Feed",
      "slug": "my-feed",
      "created_at": "2023-07-13T11:11:11Z",
      "custom_host": null,
      "website": null,
      "color": "#ffffff",
      "url": "https://my-feed.com/",
      "is_disabled": false,
      "is_unindexed": false,
      "is_private": false,
      "is_readmore": true,
      "html_inject": null,
      "metadata": {},
      "theme": {},
      "version": 1
    },
    {
      "id": "987654321",
      "project_id": "123456789",
      "name": "Another Feed",
      "slug": "another-feed",
      "created_at": "2023-07-13T1

widget

Query

The widget query is a GraphQL query that returns a widget. The query takes the following arguments:

  • project_id (required): The ID of the project that the widget belongs to.

  • widget_id (required): The ID of the widget.

Argument

  • project_id: The ID of the project that the widget belongs to.

    • This argument is required.

    • The ID must be a valid integer.

  • widget_id: The ID of the widget.

    • This argument is required.

    • The ID must be a valid integer.

Object

The Widget object that is returned by the widget query is a object with the following properties:

  • id (integer): The ID of the widget.

  • project_id (integer): The ID of the project that the widget belongs to.

  • project (object): The project that the widget belongs to.

  • created_at (string): The date and time the widget was created.

  • name (string): The name of the widget.

  • mode (string): The mode of the widget.

  • action (string): The action of the widget.

  • slug (string): The slug of the widget.

  • options (JSON object): A JSON object that contains the options for the widget.

  • theme (JSON object): A JSON object that contains the theme for the widget.

  • version (integer): The version of the widget.

  • ga_cookie_status (string): The status of the Google Analytics cookie for the widget.

  • content_to_show (string): The content to show in the widget.

Examples

The following query will return the widget with the ID 123456789 in the project with the ID 123456789:

GraphQL

{
  widget(project_id: 123456789, widget_id: 123456789) {
    id
    project_id
    created_at
    name
    mode
    action
    slug
    options
    theme
    version
    ga_cookie_status
    content_to_show
  }
}

This query will return the following JSON:
​

JSON

{
  "widget": {
    "id": "123456789",
    "project_id": "123456789",
    "created_at": "2023-07-13T11:11:11Z",
    "name": "My Widget",
    "mode": "embed",
    "action": "https://my-widget.com/",
    "slug": "my-widget",
    "options": {},
    "theme": {},
    "version": 1,
    "ga_cookie_status": "allow",
    "content_to_show": "This is the content to show in the widget"
  }
}

widgets

Query

The widgets query is a GraphQL query that returns a list of widgets. The query takes the following arguments:

  • project_id (required): The ID of the project that the widgets belong to.

Argument

  • project_id: The ID of the project that the widgets belong to.

    • This argument is required.

    • The ID must be a valid integer.

Object

The Widget object that is returned by the widgets query is a object with the following properties:

  • id (integer): The ID of the widget.

  • project_id (integer): The ID of the project that the widget belongs to.

  • project (object): The project that the widget belongs to.

  • created_at (string): The date and time the widget was created.

  • name (string): The name of the widget.

  • mode (string): The mode of the widget.

  • action (string): The action of the widget.

  • slug (string): The slug of the widget.

  • options (JSON object): A JSON object that contains the options for the widget.

  • theme (JSON object): A JSON object that contains the theme for the widget.

  • version (integer): The version of the widget.

  • ga_cookie_status (string): The status of the Google Analytics cookie for the widget.

  • content_to_show (string): The content to show in the widget.

Examples

The following query will return all of the widgets in the project with the ID 123456789:

GraphQL

{
  widgets(project_id: 123456789) {
    id
    project_id
    created_at
    name
    mode
    action
    slug
    options
    theme
    version
    ga_cookie_status
    content_to_show
  }
}

This query will return the following JSON:

JSON

{
  "widgets": [
    {
      "id": "123456789",
      "project_id": "123456789",
      "created_at": "2023-07-13T11:11:11Z",
      "name": "My Widget",
      "mode": "embed",
      "action": "https://my-widget.com/",
      "slug": "my-widget",
      "options": {},
      "theme": {},
      "version": 1,
      "ga_cookie_status": "allow",
      "content_to_show": "This is the content to show in the widget"
    },
    {
      "id": "987654321",
      "project_id": "123456789",
      "created_at": "2023-07-13T11:11:12Z",
      "name": "Another Widget",
      "mode": "embed",
      "action": "https://another-widget.com/",
      "slug": "another-widget",
      "options": {},
      "theme": {},
      "version": 1,
      "ga_cookie_status": "allow",
      "content_to_show": "This is the content to show in another widget"
    }
  ]
}

imports & import

Query

Both import and imports is a GraphQL query that returns a list of migrartions made on your project from other services. The query takes the following arguments:

  • project_id (required): The ID of the project that the imports belong to.

Tne oly difference is that, import requires your import_id, which can be found within imports

Object

The Import object that is returned by the imports query is a object with the following properties:

  • id (integer): The ID of the import.

  • project_id (integer): The ID of the project that the import belongs to.

  • user_id (integer): The ID of the user who created the import.

  • status (string): The status of the import.

  • source (string): The source of the import.

  • created_at (string): The date and time the import was created.

  • is_continuous (boolean): Whether the import is continuous.

  • message (string): A message about the import.

Examples

The following query will return all of the imports in the project with the ID 123456789:

GraphQL

{
  imports(project_id: 29289) {
    id
    project_id
    user_id
    status
    source
    created_at
    is_continuous
    message
  }
}

This query will return the following JSON:
​

JSON

{
  "data": {
    "imports": [
      {
        "id": "1053",
        "project_id": "29289",
        "user_id": "15924",
        "status": "finished",
        "source": "headway",
        "created_at": "2023-07-17T16:14:55.667Z",
        "is_continuous": false,
        "message": "Import Finished"
      }
    ]
  }
}

labels

Query

The labels query is a GraphQL query that returns a list of labels. The query takes the following arguments:

  • project_id (required): The ID of the project that the labels belong to.

Argument

  • project_id: The ID of the project that the labels belong to.

    • This argument is required.

    • The ID must be a valid integer.

Object

The Label object that is returned by the labels query is a object with the following properties:

  • id (integer): The ID of the label.

  • name (string): The name of the label.

  • color (string): The color of the label.

Examples

The following query will return all of the labels in the project with the ID 123456789:

GraphQL

{
  labels(project_id:123456789) {
    id
    name
    color
  }
}

This query will return the following JSON:

JSON

{
  "labels": [
    {
      "id": "123456789",
      "name": "Important",
      "color": "#ff0000"
    },
    {
      "id": "987654321",
      "name": "Low Priority",
      "color": "#00ff00"
    }
  ]
}

segments

Query

The segments query is a GraphQL query that returns a list of segments used in the project. The query takes the following arguments:

  • project_id (required): The ID of the project that the segments belong to.

Argument

  • project_id: The ID of the project that the segments belong to.

    • This argument is required.

    • The ID must be a valid integer.

Object

The Segment object that is returned by the segments query is a string with the following properties:

  • segment (string): The name of the segment.

Examples

The following query will return all of the segments in the project with the ID 123456789:

GraphQL

{
  segments(project_id:123456789)
}

This query will return the following JSON:

JSON

{
  "segments": [
    "marketing",
    "sales",
    "support"
  ]
}

segmentProfiles

Query

The segmentProfiles query is a GraphQL query that returns the list of segment profiles and their rules. The query takes the following arguments:

  • project_id (required): The ID of the project that the segment profiles belong to.

Argument

  • project_id: The ID of the project that the segment profiles belong to.

    • This argument is required.

    • The ID must be a valid integer.

Object

The SegmentProfile object that is returned by the segmentProfiles query is a object with the following properties:

  • project_id (integer): The ID of the project that the segment profile belongs to.

  • title (string): The title of the segment profile.

  • rules (JSON object): The rules for the segment profile.

Examples

The following query will return all of the segment profiles in the project with the ID 123456789:

GraphQL

{
  segmentProfiles(project_id: 123456789) {
    project_id
    title
    rules
  }
}

This query will return the following JSON:


JSON

{
  "data": {
    "segmentProfiles": [
      {
        "project_id": "123456789",
        "title": "Internal Team",
        "rules": "{\"filter\":[\"contains\",\"user_email\",\"internalteam.com\"]}"
      }
    ]
  }
}

externalUsers

Query

The externalUsers query is a GraphQL query that returns a paginated list of external users. The query takes the following arguments:

  • project_id (required): The ID of the project that the external users belong to.

  • filters (optional): A JSON object with filters to be applied to the query.

  • page (optional): The page number of the results to return. Defaults to 0.

  • sortField (optional): The field to sort the results by. Defaults to SEEN_AT.

  • sortOrder (optional): The sort order of the results. Defaults to DESC.

Argument

  • project_id: The ID of the project that the external users belong to.

    • This argument is required.

    • The ID must be a valid integer.

  • filters: A JSON object with filters to be applied to the query.

    • This argument is optional.

    • The object must contain a field property and a value property. The field property specifies the field to filter on, and the value property specifies the value to filter for.

  • page: The page number of the results to return.

    • This argument is optional.

    • The default value is 0.

  • sortField: The field to sort the results by.

    • This argument is optional.

    • The default value is SEEN_AT.

  • sortOrder: The sort order of the results.

    • This argument is optional.

    • The default value is DESC.

Object

The PageOfExternalUsers object that is returned by the externalUsers query is a object with the following properties:

  • page (integer): The current page number.

  • pages (integer): The total number of pages.

  • count (integer): The total number of external users.

  • items (array): An array of ExternalUser objects.

Examples

The following query will return the first page of external users in the project with the ID 123456789, sorted by the SEEN_AT field in descending order:

GraphQL

{
  externalUsers(
    project_id: 123456789
    sortField: SEEN_AT
    sortOrder: DESC
  ) {
    page
    pages
    count
    items {
      id
      email
      name
      seen_at
    }
  }
}

This query will return the following JSON:

JSON

{
  "externalUsers": {
    "page": 1,
    "pages": 10,
    "count": 100,
    "items": [
      {
        "id": "123456789",
        "email": "[email protected]",
        "name": "John Doe",
        "seen_at": "2023-07-13T11:11:11Z"
      },
      {
        "id": "987654321",
        "email": "[email protected]",
        "name": "Jane Doe",
        "seen_at": "2023-07-13T11:11:12Z"
      }
    ]
  }
}

externalUserCount

Query

The externalUserCount query is a GraphQL query that returns the number of external users in a project. The query takes the following arguments:

  • project_id (required): The ID of the project that the external users belong to.

  • filters (optional): A JSON object with filters to be applied to the query.

Argument

  • project_id: The ID of the project that the external users belong to.

    • This argument is required.

    • The ID must be a valid integer.

  • filters: A JSON object with filters to be applied to the query.

    • This argument is optional.

    • The object must contain a field property and a value property. The field property specifies the field to filter on, and the value property specifies the value to filter for.

Object

The externalUserCount object that is returned by the externalUserCount query is a object with the following properties:

  • count (integer): The number of external users.

Examples

The following query will return the number of external users in the project with the ID 123456789:

GraphQL

{
  externalUserCount(project_id: 123456789) {
    count
    capped
  }
}

This query will return the following JSON:

JSON

{
  "externalUserCount": {
    "count": 100,
    "capped": false
  }
}

externalUser

Query

The externalUser query is a GraphQL query that returns an external user. The query takes the following arguments:

  • project_id (required): The ID of the project that the external user belongs to.

  • external_user_id (required): The ID of the external user.

User id's can be found under Audience section.

Argument

  • project_id: The ID of the project that the external user belongs to.

    • This argument is required.

    • The ID must be a valid integer.

  • external_user_id: The ID of the external user.

    • This argument is required.

    • The ID must be a valid integer.

Object

The ExternalUser object that is returned by the externalUser query is a object with the following properties:

  • id (integer): The ID of the external user.

  • project_id (integer): The ID of the project that the external user belongs to.

  • created_at (string): The date and time the external user was created.

  • seen_at (string): The date and time the external user was last seen.

  • name (string): The name of the external user.

  • email (string): The email address of the external user.

  • fields (JSON object): A JSON object with custom fields for the external user.

  • is_anon (boolean): Whether the external user is anonymous.

  • is_following (boolean): Whether the external user is following the project.

  • is_email_verified (boolean): Whether the external user's email address has been verified.

  • is_imported (boolean): Whether the external user was imported from another system.

  • avatar (string): The URL of the external user's avatar.

  • is_app (boolean): Whether the external user is an app.

Examples

The following query will return the external user with the ID 123456789 in the project with the ID 123456789:

GraphQL

{
  externalUser(project_id: 123456789, external_user_id: 123456789) {
    id
    project_id
    created_at
    seen_at
    name
    email
    fields
    is_anon
    is_following
    is_email_verified
    is_imported
    avatar
    is_app
  }
}

This query will return the following JSON:

JSON

{
  "externalUser": {
    "id": "123456789",
    "project_id": "123456789",
    "created_at": "2023-07-13T11:11:11Z",
    "seen_at": "2023-07-13T11:11:12Z",
    "name": "John Doe",
    "email": "[email protected]",
    "fields": {},
    "is_anon": false,
    "is_following": false,
    "is_email_verified": true,
    "is_imported": false,
    "avatar": "https://avatars.example.com/john.doe",
    "is_app": false
  }
}

analytics

Query

The analytics query is a GraphQL query that returns analytics data for a project. The query takes the following arguments:

  • project_id (required): The ID of the project that the analytics data belongs to.

  • startDate (required): The start date of the time period for which the analytics data is being retrieved.

  • endDate (required): The end date of the time period for which the analytics data is being retrieved.

Argument

  • project_id: The ID of the project that the analytics data belongs to.

    • This argument is required.

    • The ID must be a valid integer.

  • startDate: The start date of the time period for which the analytics data is being retrieved.

    • This argument is required.

    • The date must be in the format YYYY-MM-DD.

  • endDate: The end date of the time period for which the analytics data is being retrieved.

    • This argument is required.

    • The date must be in the format YYYY-MM-DD.

Object

The Analytics object that is returned by the analytics query is a object with the following properties:

  • unsubs (integer): The number of unsubscribes.

  • subs (integer): The number of subscriptions.

  • feedback (integer): The number of feedback submissions.

  • reaction (integer): The number of reactions.

  • mail_sent (integer): The number of emails sent.

  • post_views (integer): The number of post views.

  • feed_views (integer): The number of feed views.

  • widget_imp (integer): The number of widget impressions.

  • widget_views (integer): The number of widget views.

Examples

The following query will return the analytics data for the project with the ID 123456789 for the time period from 2023-07-01 to 2023-07-31:

GraphQL

{
  analytics(project_id: 123456789, startDate: "2023-07-01", endDate: "2023-07-31") {
    unsubs
    subs
    feedback
    reaction
    mail_sent
    post_views
    feed_views
    widget_imp
    widget_views
  }
}

This query will return the following JSON:

JSON

{
  "analytics": {
    "unsubs": 100,
    "subs": 200,
    "feedback": 50,
    "reaction": 1000,
    "mail_sent": 10000,
    "post_views": 100000,
    "feed_views": 200000,
    "widget_imp": 1000000,
    "widget_views": 500000
  }
}

analyticsChart

Query

The analyticsChart query is a GraphQL query that returns a chart of analytics data for a project. The query takes the following arguments:

  • project_id (required): The ID of the project that the analytics data belongs to.

  • startDate (required): The start date of the time period for which the analytics data is being retrieved.

  • endDate (required): The end date of the time period for which the analytics data is being retrieved.

Argument

  • project_id: The ID of the project that the analytics data belongs to.

    • This argument is required.

    • The ID must be a valid integer.

  • startDate: The start date of the time period for which the analytics data is being retrieved.

    • This argument is required.

    • The date must be in the format YYYY-MM-DD.

  • endDate: The end date of the time period for which the analytics data is being retrieved.

    • This argument is required.

    • The date must be in the format YYYY-MM-DD.

Object

The AnalyticsChart object that is returned by the analyticsChart query is a object with the following properties:

  • labels (array of strings): The labels for the chart.

  • datasets (array of ChartDataset objects): The datasets for the chart.

Object

The ChartDataset object that is returned by the analyticsChart query is a object with the following properties:

  • label (string): The label for the dataset.

  • data (array of integers): The data for the dataset.

Examples

The following query will return a chart of the analytics data for the project with the ID 123456789 for the time period from 2023-07-17 to 2023-07-17: (same day)

GraphQL

{
  analyticsChart(project_id: 123456789, startDate: "2023-07-17", endDate: "2023-07-17") {
    labels
    datasets {
      label
      data
    }
  }
}

This query will return the following JSON:

JSON

{
  "data": {
    "analyticsChart": {
      "labels": [
        "17/07"
      ],
      "datasets": [
        {
          "label": "OPEN",
          "data": [
            113
          ]
        },
        {
          "label": "LOAD",
          "data": [
            1289
          ]
        },
        {
          "label": "CLOSE",
          "data": [
            52
          ]
        }
      ]
    }
  }
}

analyticsPost

Query

The analyticsPost query is a GraphQL query that returns analytics data for posts in a project. The query takes the following arguments:

  • project_id (required): The ID of the project that the analytics data belongs to.

  • startDate (required): The start date of the time period for which the analytics data is being retrieved.

  • endDate (required): The end date of the time period for which the analytics data is being retrieved.

Argument

  • project_id: The ID of the project that the analytics data belongs to.

    • This argument is required.

    • The ID must be a valid integer.

  • startDate: The start date of the time period for which the analytics data is being retrieved.

    • This argument is required.

    • The date must be in the format YYYY-MM-DD.

  • endDate: The end date of the time period for which the analytics data is being retrieved.

    • This argument is required.

    • The date must be in the format YYYY-MM-DD.

Object

The AnalyticsPost object that is returned by the analyticsPost query is a object with the following properties:

  • posts (array of AnalyticsPostItem objects): The posts for the project.

Object

The AnalyticsPostItem object that is returned by the analyticsPost query is a object with the following properties:

  • id (integer): The ID of the post.

  • title (string): The title of the post.

  • view (integer): The number of views for the post.

  • likes (integer): The number of likes for the post.

  • dislikes (integer): The number of dislikes for the post.

  • neutral (integer): The number of neutral reactions for the post.

  • comment (integer): The number of comments for the post.

Examples

The following query will return the analytics data for posts in the project with the ID 123456789 for the time period from 2023-07-01 to 2023-07-31:

GraphQL

{
  analyticsPost(project_id: 123456789, startDate: "2023-07-01", endDate: "2023-07-31") {
    posts {
      id
      title
      view
      likes
      dislikes
      neutral
      comment
    }
  }
}

This query will return the following JSON:

JSON

{
  "analyticsPost": {
    "posts": [
      {
        "id": 123456789,
        "title": "My First Post",
        "view": 1000,
        "likes": 200,
        "dislikes": 50,
        "neutral": 10,
        "comment": 50
      },
      {
        "id": 987654321,
        "title": "My Second Post",
        "view": 500,
        "likes": 100,
        "dislikes": 20,
        "neutral": 5,
        "comment": 25
      }
    ]
  }
}

Continued in GraphQL Queries for AnnounceKit — Part 2 — analyticsv3, image, plans, subscription, users, locales, and the remaining queries.

Did this answer your question?