# GraphQL queries

The GraphQL API gives you the ability to query all kinds of UserPoint data as collected by the platform (profile, activities, segments, identifiers, etc.) **with a single request**. 

Each GraphQL query is meant to fetch a **single** UserPoint data. To query multiple UserPoint in a single query, depending on your use case, please refer to the [OTQL queries](/querying-your-data/otql-queries.md) and/or to the [Query exports](/data-streams/exporting-your-data/query-exports.md).

{% hint style="info" %}
If you're not familiar with GraphQL and how to interact with such APIs, please refer to the official documentation: <https://graphql.org/>
{% endhint %}

## GraphQL schema

The schema used in the GraphQL endpoint is based on the [customer defined schema](/schema/defining-your-schema.md). To add/remove fields from the GraphQL API, the schema has to be updated accordingly.

## GraphQL endpoint

<mark style="color:green;">`POST`</mark> `/v1/datamarts/:datamartId/query_executions/graphql`

#### Path Parameters

| Name       | Type   | Description                                                  |
| ---------- | ------ | ------------------------------------------------------------ |
| datamartId | string | The datamartId in which the UserPoint data will be looked up |

#### Request Body

| Name  | Type   | Description                                                                                                                            |
| ----- | ------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| query | string | This parameter should include your GraphQL query, starting with "query MyQuery {...". Do not forget to escape double quotes if needed. |

{% tabs %}
{% tab title="200 " %}

```
{
    "data": { ...GraphQL response... }
}
```

{% endtab %}

{% tab title="429 " %}

```
{
    "error": "..."
}
```

{% endtab %}
{% endtabs %}

## GraphQL editor

To test and write GraphQL queries, we recommend you using our GraphQL editor:

1. Head to the Computing Console
2. Click on GraphQL menu under DATA STUDIO section

## Limits

Through the GraphQL endpoint, only queries (reads) are supported. Mutations (writes) are not supported.

This endpoint is being rate-limited and will respond with 429 HTTP status code if the QPS exceed its limits. Please discuss with your account manager to have more information about this rate limiting and to request any limit increase.

{% hint style="warning" %}
The user activities number retuned is also limited. A query return to **maximum 100 activities**. Be careful, there is not warning and you can't change this limit yet. &#x20;

Moreover, an user event is always in an activity so, this limitation is indirectly apply on the events. The query will return only the event in the hundred first activities.
{% endhint %}

## Query examples

```graphql
# Return the UserPoint creation_ts field
query MyQuery {
  user_point(user_point_id: "xxxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx") {
    creation_ts
  }
}
```

```graphql
# Return profiles, accounts, segments and scenarios data of a UserPoint
# Warning: This query relies on a customer defined schema so it may not
# work as-is on your datamart.
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
    }
  }
}
```

## Selecting a UserPoint

You can select a UserPoint by any identifier using different functions.

```graphql
# Select by UserPoint ID
query MyQuery {
  user_point(user_point_id: "xxxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx") {
    id
    creation_ts
  }
}

# Select by email hash
query MyQuery {
  user_point_by_email_hash(email_hash: "xxxxxxxxxxxxxxxxxxx") {
    id
    creation_ts
  }
}

# Select by user account
# Both compartment ID and user account ID are mandatory
query MyQuery {
  user_point_by_user_account_id(
    compartment_id: "XXXX",
    user_account_id: "xxxx-xxx-xx-xxxxx"
    ) {
    id
    creation_ts
  }
}

# Select by user agent ID
query MyQuery {
  user_point_by_user_agent_id(user_agent_id: "xxxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx"){
    id
    creation_ts
  }
}
```

For more information, see [User identifiers](/user-points.md#user-identifiers)

## Filters

To only select elements matching a specific clause, use `@filter`. This clause is a WHERE object tree expressions, so you can use any thing like it was this kind of expression.&#x20;

```graphql
query micsQuery {
  user_point(user_point_id:"xxx") {
    activities {
      #only return events with the name "$home_view"
      events @filter(clause: "name == \"$home_view\""){ 
        ts
      }
    }
  }
}
```

{% hint style="warning" %}
Be carful the `@filter` is applied **after the limitation** of the activities. So if your query does not return activities it only mean there isn't activities which respect your condition in the hundred first of the UserPoint select.&#x20;
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.mediarithmics.io/querying-your-data/graphql-queries.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.