Query HubSpot data using GraphQL

Supported products

Requires one of the following products or higher.

Sales HubEnterprise

Service HubEnterprise

Content HubProfessional

• If you have a Content Hub Professional or Enterprise subscription, you can use GraphQL to fetch data for website pages.
• If you have a Sales Hub or Service Hub Enterprise subscription, you can use GraphQL to fetch data for UI extensions.

​

Advantages of using GraphQL

​

GraphQL schema and queries

query MyQuery {
  # Root query field
  CRM {
    # Child fields
    contact_collection {
      items {
        # Properties
        email
        firstname
        lastname
      }
    }
  }
}

• Root query field: the top-level field of your query that represents your data source. The available data sources are:
  • CRM: records (e.g., contacts, companies, etc.) and other data from your CRM.
  • HUBDB: data from a HubDB table.
  • BLOG: data from blog posts, authors, and tags.
  • KB: data from your knowledge base, including articles, categories, and tags.
• Child fields: based on the data source in your root query field, you can then specify the child fields you want to fetch, along with any associated properties.

​

Query data from your CRM

• Standard and custom objects
• Engagements, including calls, tasks, meetings, and notes
• Products and line items
• Quotes and subscriptions
• Marketing events

• Fetch a single instance: if you’re fetching a single instance like an individual contact record, specify one of the object’s properties and its associated value by including the property’s name as the uniqueIdentifier, and the property’s value as the uniqueIdentifierValue. For example, the following query would fetch a contact with an ID of 753:

query filteredContact {
  CRM {
    contact(uniqueIdentifier: "id", uniqueIdentifierValue: "756") {
      email
    }
  }
}

• Fetch and filter a collection: to fetch a collection of instances, add items as a child field. To filter the objects in the response, include the filter argument, then provide a map of filter operators to their associated values. A filter operator consists of the property you want to filter by, followed by a suffix. For example, the query below would fetch and filter a collection of contacts with hubspot.com email addresses:

query filteredContactCollection {
  CRM {
    contact_collection(filter: { email__contains: "hubspot.com" }) {
      items {
        email
      }
    }
  }
}

• Add properties to fetch: enter the internal name of a property to include it in the response of your query. Both default and custom properties are supported.
• Include associations to other data types: you can also add a collection of instances of a data type associated with the parent data type, such as the companies associated with a contact. To add data from an associated data type:
  • Include associations as a child field of the original data type you entered.
  • As a child field of associations, enter the association you want to include by following the naming scheme of {ASSOCIATED_DATA_TYPE}_collection__{LABEL_SUFFIX}.
    • The associated data type can be a built-in association with a standard object, or an association with a custom object. Any associations to custom objects will be prefixed by p_.
    • For primary associations, the label suffix is primary. If you created a custom association label, the label suffix will be lower-cased, with each word in the label separated by an underscore. For example, if your custom association label is My custom association label, the label suffix would be my_custom_association_label.
    • For example, if you had a custom object named House associated with the contact object, the association you’d include in your query would be p_house_collection__house_to_contact.
  • Add items as a child field of your association, then include any properties you need from each item in the collection.

query contactsWithAssociatedCompany {
  CRM {
    contact_collection {
      items {
        firstname
        lastname
        associations {
          company_collection__primary {
            items {
              name
              address
            }
          }
        }
      }
    }
  }
}

​

Query data from HubDB

• Retrieve a single row: if you’re retrieving a single row from a table, specify one of the table’s columns as the uniqueIdentifier then provide the associated value of the row you want to retrieve as the uniqueIdentifierValue. For example, the following query would retrieve a row from an executives table with a role of CEO:

query filteredExecutive {
  HUBDB {
    executives(uniqueIdentifier: "role", uniqueIdentifierValue: "CEO") {
      name
      email
      description
    }
  }
}

• Retrieve and filter multiple rows: to fetch multiple rows from a table, add items as a child field. To filter the rows in the response, include the filter argument to your query field, then provide a map of filter operators to their associated values. A filter operator consists of the property you want to filter by, followed by a suffix. For example, the query below would retrieve and filter rows from the executives table whose role contains O__fficer:

query csuiteExecutives {
  HUBDB {
    executives_collection(filter: { role__contains: "Officer" }) {
      items {
        email
      }
    }
  }
}

• Add columns to retrieve: enter the name of a column to include it in the response to your query. If one of your columns is a foreign ID and you want to include columns from the associated table:
  • Include associations as a child field of items.
  • As a child field under associations, enter the name of the foreign table with the _collection suffix, followed by two underscores and the name of the foreign ID column. For example, if the foreign ID column is recent_posts, and the name of the foreign table you want to reference is blog_posts, then the resulting field to include in your query would be blog_posts_collection__recent_posts.
  • Add items as a child field of the foreign table field you just entered, then include any columns you need from the foreign table. For example, to include additional columns from the executives table from the csuiteExecutives query above, along with the title and link from a blog_posts foreign table, you’d update the query to the following:

query csuiteExecutives {
  HUBDB {
    executives_collection(filter: { role__contains: "Officer" }) {
      items {
        associations {
          blog_posts_collection__recent_posts {
            items {
              title
              link
            }
          }
        }
        email
        name
        description
        role
      }
    }
  }
}

• Include metadata fields: internal properties of the table, such as the ID or the timestamp of the last update to a row, are prefixed with hs_.

​

Retrieving data from child tables

• Add hs_child_table_collection as a child field of the items of the parent table collection.
• For each child table that you want to include, include a nested child fragment, which consists of the spread operator (i.e., ...) combined with a type condition, which includes the on keyword and the name of the child table collection. For example, if you wanted to update the csuiteExecutives query from above to include columns from the team and recent_posts child tables:

query csuiteExecutives {
  HUBDB {
    executives_collection(filter: { role__contains: "Officer" }) {
      items {
        email
        name
        description
        role
        hs_child_table_collection {
          ... on teams_collection {
            name
            email
            summary
          }
          ... on recent_posts_collection {
            title
            summary
            link
          }
        }
      }
    }
  }
}

​

Retrieving unpublished data from a table

query csuiteExecutives {
  HUBDB {
    executives_collection(draft: true, filter: { role__contains: "Officer" }) {
      items {
        email
        name
        description
        role
        hs_id
        hs_child_table_id
      }
    }
  }
}

​

Query blog data

• Post and post collection
• Author and author collection
• Tag and tag collection

query MyQuery {
  # Root query field
  BLOG {
    # Child fields
    post_collection {
      items {
        # Properties
        name
        post_body
      }
    }
  }
}

• Retrieve a single blog post: retrieve the title and content of a single blog post by using its ID as the uniqueIdentifier.

query MyQuery {
  BLOG {
    post(uniqueIdentifier: "id", uniqueIdentifierValue: "123") {
      name
      post_body
    }
  }
}

• Retrieve blog author fields from a post: retrieve the title and content of a single blog post, along with the blog author’s name and email address, by using its ID as the uniqueIdentifier.

query MyQuery {
  BLOG {
    post(uniqueIdentifier: "id", uniqueIdentifierValue: 123) {
      name
      post_body
      blog_author {
        full_name
        email
      }
    }
  }
}

• Retrieve a filtered collection of blog posts: retrieve a set of blog posts filtered by the post title.

query MyQuery {
  BLOG {
    post_collection(filter: { name__icontains: "blog" }) {
      items {
        name
        post_body
      }
    }
  }
}

• Retrieve drafted blog posts: retrieve a collection of blog posts that are not currently published by specifying draft: true.

query MyQuery {
  BLOG {
    post_collection(draft: true, filter: { name__icontains: "blog" }) {
      items {
        name
        post_body
      }
    }
  }
}

​

Query knowledge base data

• Knowledge base and knowledge base collection
• Articles and article collection
• Category and category collection
• Tag and tag collection

query MyQuery {
  # Root query field
  KB {
    # Child fields
    knowledge_article_collection {
      items {
        # Properties
        name
        post_body
      }
    }
  }
}

• Retrieve a single knowledge base article: retrieve the title and content of a single blog post by using its ID as the uniqueIdentifier.

query MyQuery {
  KB {
    knowledge_article(
      uniqueIdentifier: "hs_id"
      uniqueIdentifierValue: "179889003802"
    ) {
      hs_name
      hs_body
    }
  }
}

• Retrieve a filtered collection of knowledge base articles: retrieve a set of articles filtered by the article title.

query MyQuery {
  KB {
    knowledge_article_collection(filter: { hs_name__contains: "cats" }) {
      items {
        hs_body
        hs_name
        hs_path
      }
    }
  }
}

​

Test and run queries interactively using GraphiQL

• In your HubSpot account, navigate to the GraphiQL tool.
• In the left pane, create and edit your query by specifying the objects and their associated fields you’ll need for your website pages.

• To view all available data types, properties, and filters, click Explorer at the top of the page to toggle the Explorer view, which will list all available data types and their associated properties.
  • Click a data type to automatically add it to your query and view all its associated properties.
  • Select the checkbox next to a property to add it to your query.
  • If you’re writing a query and you’re entering an argument for one of your fields, the Explorer pane will auto-populate a list of available filters.
• When you’re ready to test a query, click the play icon at the top of the page. The query’s response will appear in the right pane.

​

Filter and refine query results

​

Query argument types

​

Paginating results

CRM {
  contact_collection(offset: 10, limit: 30) {
    offset
    limit
    total
    items {
      firstname
      lastname
    }
  }
}

​

Combine multiple filters and use conditional logic

​

Use OR logic when querying CRM data

CRM {
  p_job_collection(filter: {
    OR: [
      {status__eq: "full-time"},
      {status__eq: "contract"}
    ]
  }) {
    items {
       # Job child fields (e.g., name, id, etc.)
    }
  }
}

CRM {
  p_job_collection(filter: {
    OR: [
      {status__eq: "full-time"},
      {department__eq: "engineering"}
    ]
  }) {
    items {
       # Job child fields (e.g., name, id, etc.)
    }
  }
}

CRM {
  p_job_collection(filter: {
    status__eq: "full-time", OR: [
      {department__eq: "engineering", salary__gt: 80000},
      {department__eq: "sales", salary__gt: 100000}
    ]
  }) {
    items {
      # Job child fields (e.g., name, id, etc.)
    }
  }
}

​

Query complexity and account limits

​

Limit on maximum items returned in a query

​

Query complexity and account limits

• Internal API request: 300 points
• Object retrieved: 30 points
• Requested property with a value: 3 points
• Requested property without a value: 1 point

query myQuery {
  CRM {
    contact_collection {
      items {
        hs_object_id
        firstname
        lastname
        email
        company
        associations {
          company_collection__primary {
            items {
              hs_object_id
              name
              domain
              country
              annualrevenue
              phone
              associations {
                ticket_collection__primary {
                  items {
                    hs_object_id
                    createdate
                    content
                    created_by
                    hs_pipeline
                    hs_pipeline_stage
                    closed_date
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

• Points used for contact_collection:
  • One internal API request is made (300 points).
  • 10 contacts are retrieved (10 * 30 = 300 points).
  • For each contact, five properties with values are retrieved (10 * 5 * 3 =150 points).
  • Total points: 750
• Points used for company_collection__primary:
  • One internal API is made per contact retrieved, totaling 10 requests (10 * 300 = 3,000 points).
  • Six companies are retrieved (6 * 30 = 180 points).
  • Five properties are retrieved with a value per company (6 * 5 * 3 = 90 points).
  • One property is returned with no value per company (6 * 1 = 6 points).
  • Total points: 3,276
• Points used for ticket_collection__primary:
  • One internal API request is made per company per contact retrieved (10 * 6 * 300 = 18,000 points).
  • 15 tickets are returned (15 * 30 = 450 points).
  • Seven properties are returned with a value per ticket (15 * 7 * 3 = 315 points).
  • Total points: 18,765

• Each individual query has a maximum of 30,000 points available. If this limit is reached while the query is running, all further execution is blocked and all object instances fetched up to that point are returned.
• Each HubSpot account is allowed up to 500,000 points per rolling minute when using the GraphQL API endpoint. If this limit is reached, further requests to the endpoint will receive an HTTP status code of 429 Too Many Requests. The only exception is that templates and modules with GraphQL queries loaded by site visitors will continue to function to preserve website user experience. All other ad-hoc uses of the endpoint will no longer function (e.g., during template/module development, using the GraphiQL UI, and UI extensions using GraphQL queries). Accumulated points from the previous minute are not carried over to the next.
• The normal burst limits detailed in HubSpot’s API usage guidelines are not applicable to querying data using GraphQL.

• The complexity score for the query you provided in your request will be broken down within the query_complexity field.
• If you’re using the external GraphQL API endpoint, the extensions field will also include account limit information within rate_limit_info.

"extensions": {
  "rate_limit_info": {
    "interval_in_seconds": 60,
    "max_points": 500000,
    "remaining_points": 477209,
   }
  "query_complexity": {
    "max_points": 30000,
    "used_points": 22791,
    "points_for_internal_api_requests": {
      "count": 71,
      "weight": 300,
      "used_points": 21300
    },
    "points_for_objects_retrieved": {
      "count": 31,
      "weight": 30,
      "used_points": 930
    },
    "points_for_properties_with_value": {
      "count": 185,
      "weight": 3,
      "used_points": 555
    },
    "points_for_properties_without_value": {
      "count": 6,
      "weight": 1,
      "used_points": 6
    }
  }
}

​

Use a GraphQL query in an API request

​

Scope requirements

collector.graphql_schema.read
collector.graphql_query.execute

​

Make an API request to the /collector/graphql endpoint

// POST request body to https://api.hubapi.com/collector/graphql
{
  "operationName": "houses"
  "query": "query houses ($city: String) { CRM
            {house_collection(filter: {city__eq: $city}) { items {
            asking_price bedrooms bathrooms city}}}}",
  "variables": {"city": "Miami"}
}

{
  "data": {
    "CRM": {
      "house_collection": {
        "items": [
          {
            "asking_price": 800000,
            "bedrooms": 3,
            "bathrooms": 2,
            "city": "Miami"
          }
          {
            "asking_price": 940000,
            "bedrooms": 2,
            "bathrooms": 2,
            "city": "Miami"
          }
        ]
      }
    }
  }
}

​

Further reading