> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.withpersona.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.withpersona.com/_mcp/server. # Running Graph Queries > Run graph query templates through the API and retrieve their results. > **Info** > > Learn more in the [Graph API documentation](/api-reference/graph) ## Run a graph query via API ### Request Run a graph query by creating a POST request to the graph queries resource. You will need to specify a [graph query template](/graph-query-templates) and the parameters it needs: **`curl`** ```curl curl API_KEY=YOUR_API_KEY_HERE curl -X POST -H 'Content-Type: application/json' \ -H "Authorization: Bearer $API_KEY" -d'{ "data": { "attributes": { "graph-query-template-id": YOUR_TEMPLATE_ID, "parameter-map": { "example-key": "example-value", "...": "... } } } }' https://api.withpersona.com/api/v1/graph-queries ``` In `parameter-map`, include each parameter defined in your graph query template and the value you want to pass in. For example, if your graph query template contains a parameter called `account-id`, your `parameter-map` may look like this: **`text`** ```text text { "account-id": "act_UqdkF248jR4yH8xxixsMhKnt" } ``` The request payload accepts the following fields: | Field | Description | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `graph-query-template-id` | The ID of the [graph query template](/graph-query-templates) you want to run. | | `parameter-map` | A map of the parameters defined in your graph query template to the values you want to pass in. Either `parameter-map` or `variable-map` is required. | | `variable-map` | Deprecated. Use `parameter-map` instead. | | `timeout-in-seconds` | Optional. The maximum number of seconds (up to 60) to wait for the query to complete. | By default, queries run asynchronously: the query is queued for processing and the response includes a graph query ID that you can use to poll for the query result. If you pass `"meta": { "run-sync": true }` in the request, the query is processed synchronously and the response includes the completed result (or the result accumulated so far). ### Response A successful `POST` returns a `201 Created` response and includes a graph query ID that you can use to poll for the query result: **`json`** ```json json { "data": { "type": "graph-query", "id": "grphq_yourfirstqueryid", "attributes": { "params": { }, "created-at": DATE_TIME_STRING, "completed-at": null, "status": "submitted", ... } } } ``` ## Get graph query results via API ### Request Fetch the results of a graph query using the graph query ID: **`curl`** ```curl curl API_KEY=YOUR_API_KEY_HERE curl -X GET -H 'Content-Type: application/json' \ -H "Authorization: Bearer $API_KEY" \ https://api.withpersona.com/api/v1/graph-queries/GRAPH_QUERY_ID ``` Each new graph query's status starts as `submitted`. Once the `status` is `completed`, the results are available in the response. ### Response A completed graph query contains the following fields: **`json`** ```json json { "data": { "type": "graph-query", "id": "grphq_yourfirstqueryid", "attributes": { "status": "completed", "params": { }, "created-at": DATE_TIME_STRING, "updated-at": DATE_TIME_STRING, "errored-at": null, "completed-at": DATE_TIME_STRING, "redacted-at": null, "stats": {}, "explorer-url": LINK_TO_VISUALIZE_QUERY_IN_PERSONA_DASHBOARD, "node-limit-reached": false, "nodes": [ { "type": "account", "value": "act_123example" }, { "type": "device_fingerprint", "value": "123example" }, ... ] } } } ``` | Item in Response | Description | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `status` | The status of the graph query. It is initially `submitted` and becomes `completed` once Persona is done processing the data. | | `params` | The same parameters you passed in when the graph query was created. | | `created-at` | The timestamp of when the graph query was first created. | | `updated-at` | The timestamp of when the graph query was last updated. | | `errored-at` | The timestamp of when the graph query resulted in an error, if any. | | `completed-at` | The timestamp of when the graph query result was done being computed (if it is completed) | | `redacted-at` | The timestamp of when the graph query result was redacted, if any. | | `stats` | An `object` containing aggregate statistics about the query result. This is empty (`{}`) by default; for select customers it contains custom aggregation statistics. | | `explorer-url` | For any more advanced investigation, it is easiest to use our powerful suite of tools and visualization in Graph Explorer. This link opens your query result there so you can continue your analysis without having to rerun the query. | | `node-limit-reached` | Whether the node limit was reached while computing the result. See the section below for more details. | | `nodes` | An array of node objects comprised of attributes defined below. | | `value` | The value of the node that Graph used to determine a match | | `type` | The type of node, such as `account` or `device_fingerprint` | | `accounts` | The accounts surfaced by the query result, included as a relationship. | If your team would like to get additional data in the API response, please let your Persona Account Team contact know. ### About node limits Every graph query requires processing huge amounts of data and analyzing the relationships between many data nodes. To ensure performant queries, the computation will not continue traversing more nodes once it hits the graph query's specified node limit. When a graph computation hits the node limit, it will return the results it has accumulated so far. Thus, if `node-limit-reached` is `true`, the results may only reflect the portion of the possible results. If you would like to get paginated results, please reach out to your Persona Graph contact. ## Best practices For optimal query performance, try to keep the range of nodes being queried over small. For example: * In general, a query over a smaller `created-at` time range will be faster. * In general, a query on a more unique node type, such as government ID number, will compute faster than a query on a node type with lots of matches, such as name.