> For the complete documentation index, see [llms.txt](https://docs.parameter1.com/basecms-graphql/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.parameter1.com/basecms-graphql/querying-data/retrieving-published-content.md). # Retrieving published content A guide to using the \`allPublishedContent\` query to retrieve content via the BaseCMS GraphQL API ## Connecting to the API *For a high-level overview of GraphQL and connection information, review the* [*Getting Started*](/basecms-graphql/master.md) *section.* In this guide, we'll be using the [GraphQL Playground](https://github.com/graphql/graphql-playground) client. You can feel free to use any API client but we think the GraphQL Playground has the best native autocompletion and schema visibility. Other commonly used clients are [Insomnia](https://insomnia.rest/), [Altair](https://altair.sirmuel.design), or [Postman](https://www.postman.com/). {% hint style="info" %} You'll need the following information to read data from the API: * An API URL * A Tenant Key * An active Base user with permission to read data If you're missing any of this information, please reach out to and we'd be happy to provide it! {% endhint %} To get started, open the GraphQL Playground client and select New Workspace. Select the option to use a URL endpoint, and input your API URL: ![Creating a new workspace in the GraphQL Playground client](https://3551656615-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJmAeLxWsdoZNmpFobC%2F-MXgjYT0CWiykOnkxwLP%2F-MXgpFyQGALKz8jW5JYY%2Fnew-workspace.png?alt=media\&token=ead9ec7b-a43f-48e8-b3be-e0348c7798be) Once you click open, your workspace will open up. Before you can make any queries against the API, you need to identify yourself. To do so, add the `x-tenant-key` header to your client's configuration. In the GraphQL Playground, you can add that to the "HTTP Headers" tab: ![Setting the tenant key header and a basic "ping" query.](https://3551656615-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJmAeLxWsdoZNmpFobC%2F-MXgjYT0CWiykOnkxwLP%2F-MXgplx1URT2RynszGmV%2Ftenant-key.png?alt=media\&token=729fb155-f783-417d-80f7-6eff9c737010) {% hint style="info" %} Now that you've configured your API client, you can use a feature of GraphQL called introspection. Introspection allows you to browse the schema from your client, without access to the underlying codebase. To browse the schema, you can use the "Schema" (Raw output) or "Docs" (searchable, with comments) tabs on the right side of the screen. {% endhint %} ## Making a Query The most commonly used query in our GraphQL API is the `allPublishedContent` query. This query returns published content and provides a multitude of available inputs to limit, filter, and sort the results. To start, lets enter the query and review the available inputs: ![The basic \`allPublishedContent\` query](https://3551656615-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJmAeLxWsdoZNmpFobC%2F-MXgjYT0CWiykOnkxwLP%2F-MXgrcNPCJL0Mct_7jpb%2Fimage.png?alt=media\&token=d75d1fb9-cb1a-4d2c-b6dc-e12a5b989a61) ![The GraphQL query documentation for \`allPublishedContent\` and related input.](https://3551656615-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJmAeLxWsdoZNmpFobC%2F-MXgjYT0CWiykOnkxwLP%2F-MXgs6c7QtCbF3bhdPm6%2Fimage.png?alt=media\&token=fd789ea5-ce86-416e-a31e-160b9734f33c) ### Parsing the response The GraphQL type returned from this query is the `ContentConnection`. The `ContentConnection` has three properties: The total number of results available, the edge nodes (the content abstraction), and metadata about pagination. In our query above, we see that the total number of items matching our query is 49. However, the default number of items returned from this query is only 10! In order to retrieve the remaining items, we have two choices: modify the pagination limit to return all results or use cursor pagination. {% hint style="warning" %} The `limit` input can only be used up to a maximum of 200 results. Due to a limitation of the underlying technology, using a `limit+skip` strategy will be unable to retrieve all results. If querying for more than 200 pieces of content, we highly recommend using cursor pagination. {% endhint %} #### Limiting results To adjust the query limit, include the `pagination` field along with your query input. The pagination field has two supported input modes: using a limit+skip or using a cursor hash (preferred). ![Using a \`limit\` to return more than the default number of results.](https://3551656615-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJmAeLxWsdoZNmpFobC%2F-MXgjYT0CWiykOnkxwLP%2F-MXgu0ECOVoS-pqJpsAC%2Fimage.png?alt=media\&token=357b3b76-b56e-4892-aaaa-918e85eafb6d) #### Cursor Pagination The other option is to use a feature called cursor pagination. When you make your query, a computed hash of all your input options is stored and used to compute your place within the set of results -- almost like a bookmark. To see the cursor for your query, include the `pageInfo.endCursor` field. Tip: `pageInfo.hasNextPage` can be used to determine if you've reached the end of the results. ![A query returning cursor pagination details.](https://3551656615-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJmAeLxWsdoZNmpFobC%2F-MXgjYT0CWiykOnkxwLP%2F-MXgujKZ13OcUhwydel1%2Fimage.png?alt=media\&token=8faf5482-d051-4414-81ba-190ba74c5216) You can then use the `pageInfo.endCursor` with the `pagination.after` input to retrieve the next page of results: ![Page 2 retrieved using the previous query's cursor.](https://3551656615-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJmAeLxWsdoZNmpFobC%2F-MXgjYT0CWiykOnkxwLP%2F-MXguyyy4NmfFqM-nIbr%2Fimage.png?alt=media\&token=970e3d8e-03fa-4fe8-95c8-a600aed7c5e0) ## Filtering the response data As mentioned above, the `allPublishedContent` query has many available inputs to modify the returned results. In this example we're going to use the `since` and `after` inputs to limit the results to items published within a certain date range. For more input options, feel free to browse the query schema in your client! ### Date input format All `Date` inputs in the GraphQL API expect to receive a Unix timestamp with millisecond precision. You can convert a date to a timestamp by using a utility such as [Unixtimestamp](https://unixtimestamp.com). {% hint style="info" %} Most timestamp conversions will not add millisecond precision to a timestamp. If your timestamp is only using second precision, add 3 `0`'s to the end of the timestamp: `1604206812 => 1604206812000` {% endhint %} The following query returns content published `after` Nov 1 2020 and before (`since`) Jan 1 2021: ![Querying for published content using the \`after\` and \`since\` inputs.](https://3551656615-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJmAeLxWsdoZNmpFobC%2F-MXgveaGWuXH4q0qZOZM%2F-MXgy2s3SwhN5GY6Bp9H%2Fimage.png?alt=media\&token=9bd20125-87a9-4710-867f-9ffd0d1ee7db) ## Content fields The `edges.node` items returned in the query are an abstraction around the `Content` type. For all available fields, see the schema documentation for the `Content` type -- we'll show a subset below. ### Related Content To return the documents specified in the `related content` field, use the `relatedContent` field on the `Content` type. This field supports many inputs (and the same pagination options as the `allPublishedContent` query), in this example we'll use `includeContentTypes` to limit the results to only related `Company` content items. We'll also use a GraphQL feature called aliasing to call this field `companies` in the result. ### Type-specific fields While most fields are common across all content types, some fields are specific to the individual type definition. In this example, we'll output the `linkUrl` and `linkText` fields, which are only present on the `ContentPromotion` type. To do this, we're using a GraphQL feature called an inline fragment -- we're including the fields within the query directly, but only if the `ContentEdge` node is a `ContentPromotion`. ![A GraphQL query using \`relatedContent\` to show related companies and output type specific fields.](https://3551656615-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJmAeLxWsdoZNmpFobC%2F-MXgynsAIIK2_d9EQ0ij%2F-MXh1DYpGusUPXSJH4XY%2Fimage.png?alt=media\&token=b2b7eb77-d7ce-466a-9032-11142b9aed01) {% hint style="success" %} That's all for now! If you have any specific questions about using the GraphQL API or have suggestions on how this guide can be improved, please let us know via . Please feel free to leave feedback on this page and let us know what you think. {% endhint %}