GFQL Endpoint

The GFQL (graph dataframe query language) endpoint is a Graphistry server HTTP endpoint for securely dispatching GFQL queries to run over data already uploaded into your server and getting back the results. See 10 mins to GFQL for more information about GFQL and how it can be used.


POST /datasets/{dataset_id}/gfql

This endpoint accepts requests to perform graph query operations and returns graph data.


Requests to this endpoint require a valid JWT token passed as a Bearer token in the Authorization header.

Authorization: Bearer <your_jwt_token>

Request Parameters

URL Parameters:

  • dataset_id (required): The unique identifier of the dataset to query.

Query Parameters:

  • format (optional): Specifies the response data format. Currently, only json is supported. Defaults to json if unspecified.

Body Parameters (JSON):

Operations can be performed on elements matched in the sequence. In addition a subgraph is extracted from the graph composed of all elements traversed.
Parameter Type Default Description
gfql_operations Object[] - An array of operation objects used to define a sequence of graph traversals. Each operation object defines a token in the match pattern used to traverse the graph. See GFQL operations for more information on how to specify a single operation.
format string json String which specifies the format used to encode graph data returned. Valid strings include "json". Contact staff about arrow format if interested.


The response will be a JSON object containing the manipulated graph data based on the applied GFQL operations.

Example Request

curl -X POST "http://<host>/datasets/<dataset_id>/gfql?format=json" \
 -H "Authorization: Bearer <your_jwt_token>" \
 -H "Content-Type: application/json" \
 -d '{"gfql_operations":[{"type": "Node", "filter_dict":{"name": "Alice"}}, {"type": "Edge", "direction": "forward", "hops": 1}]}'

Example Response

  "nodes": [
    {"id": "1", "name": "Alice", "age": 30},
  "edges": [
    {"source": "1", "target": "2", "relation": "knows"}


  • Ensure the JWT token used for authentication has sufficient permissions to access the dataset.
  • The gfql_operations parameter allows for significant flexibility in query construction; refer to the GFQL specification for detailed usage.