> For the complete documentation index, see [llms.txt](https://docs.mediarithmics.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mediarithmics.io/setup-and-monitor/operate-and-monitor/query-your-datamart/graphql-queries.md).
# GraphQL queries
Fetch everything the platform knows about one user, in a single request.
## Your goal
Get all kinds of data about **one** UserPoint - profile, activities, segments, identifiers - with a single request, fast enough for real-time use.
## Expected outcome
A query returning exactly the fields your use case needs, within the endpoint's documented limits.
## What the GraphQL API is for
The GraphQL API gives you the ability to query all kinds of UserPoint data as collected by the platform, **with a single request**.
{% hint style="warning" %}
**Each GraphQL query fetches a single UserPoint.** To query several UserPoints in one go, use [OTQL](/setup-and-monitor/operate-and-monitor/query-your-datamart/otql.md) or a [query export](/setup-and-monitor/collect-and-manage-your-data/export-your-data/export.md), depending on your use case.
{% endhint %}
The schema used by the GraphQL endpoint is based on **your** [schema](/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/schema-definition.md). To add or remove fields from the GraphQL API, update the schema.
## The endpoint
```
POST /v1/datamarts/:datamartId/query_executions/graphql
```
| Parameter | Description |
| ------------ | ------------------------------------------------- |
| `datamartId` | The datamart in which the UserPoint is looked up. |
The body carries a `query` parameter containing your GraphQL query, starting with `query MyQuery {`. Escape double quotes where needed.
A `200` returns `{ "data": { ...GraphQL response... } }`. A `429` means you have exceeded the rate limit.
## Limits
{% hint style="danger" %}
* **Read-only.** Only queries are supported; **mutations are not**.
* **Rate-limited.** The endpoint responds with `429` when the queries-per-second rate exceeds its limits. Discuss the applicable rate, and any increase, with your account manager.
* **A query returns a maximum of 100 activities.** There is **no warning**, and the limit cannot be changed. Because an event always belongs to an activity, the limit applies indirectly to events: only events within the first hundred activities are returned.
{% endhint %}
That last limit is the one that produces wrong conclusions rather than errors - see the `@filter` warning below.
## Selecting the UserPoint
Any identifier works, through a different function.
{% tabs %}
{% tab title="By UserPoint ID" %}
```graphql
query MyQuery {
user_point(user_point_id: "xxxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx") {
id
creation_ts
}
}
```
{% endtab %}
{% tab title="By email hash" %}
```graphql
query MyQuery {
user_point_by_email_hash(email_hash: "xxxxxxxxxxxxxxxxxxx") {
id
creation_ts
}
}
```
{% endtab %}
{% tab title="By account" %}
Both the compartment ID and the account ID are **mandatory**.
```graphql
query MyQuery {
user_point_by_user_account_id(
compartment_id: "XXXX",
user_account_id: "xxxx-xxx-xx-xxxxx"
) {
id
creation_ts
}
}
```
{% endtab %}
{% tab title="By user agent ID" %}
```graphql
query MyQuery {
user_point_by_user_agent_id(user_agent_id: "xxxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx"){
id
creation_ts
}
}
```
{% endtab %}
{% endtabs %}
The identifier types are described in [User identifiers](/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/user-identity/user-identifiers.md).
## A fuller query
```graphql
query MyQuery {
user_point(user_point_id: "xxxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx") {
id
creation_ts
profiles {
gender
birth_date
}
accounts {
compartment_id
user_account_id
}
segments {
id
}
scenarios {
scenario_id
}
}
}
```
{% hint style="info" %}
This query relies on a **customer-defined schema**, so it may not work as-is on your datamart. Check your own field names before copying it.
{% endhint %}
## Filtering
`@filter` selects only the elements matching a clause. The clause is a `WHERE` object tree expression, so anything valid there is valid here.
```graphql
query micsQuery {
user_point(user_point_id:"xxx") {
activities {
events @filter(clause: "name == \"$home_view\""){
ts
}
}
}
}
```
{% hint style="danger" %}
**`@filter` is applied *****after***** the 100-activity limitation.**
So an empty result does **not** mean the user has no matching activity - it means there is none **among the first hundred activities** of that UserPoint. For a user with a long history, a filter on an older event will find nothing while the event exists.
When you need to search a full history, use [OTQL](/setup-and-monitor/operate-and-monitor/query-your-datamart/otql.md) instead.
{% endhint %}
## Tools
Use a dedicated editor to write and test GraphQL queries. A GraphQL playground is available in the Computing Console.
## Related pages
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.mediarithmics.io/setup-and-monitor/operate-and-monitor/query-your-datamart/graphql-queries.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.