---
updatedAt: 2026-04-23T18:12:51.000Z
agentTools:
  siteIndex: https://developers.pismo.io/llms.txt
  projectIndex: https://developers.pismo.io/pismo-docs/llms.txt
---

# Get tracking graph [beta]

Get tracking graphs.

Retrieves the tracking graph that maps the chain of subsequent transactions originated from the dispersion of fraudulent funds.

The graph identifies people, accounts, and transactions involved in the movement of diverted funds.

You can call this endpoint if you are:
 * The funds recovery creator participant
 * Counterparty participants who received related infraction notifications


# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Instant payments - Pix management",
    "description": "API responsible for providing Pix operations (related to DICT) via integrating with external providers",
    "contact": {
      "name": "API Support",
      "url": "https://developers.pismo.io/support/"
    },
    "license": {
      "name": "Copyright Pismo"
    },
    "version": "0.0.1"
  },
  "servers": [
    {
      "url": "https://sandbox.pismolabs.io/pix-dict",
      "description": "Sandbox API server for testing."
    }
  ],
  "tags": [
    {
      "name": "Funds recovery"
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    },
    "parameters": {
      "FundsRecoveryIdPath2": {
        "name": "funds_recovery_id",
        "in": "path",
        "description": "Funds recovery identifier. \n\nReturned from the [Create funds recovery](https://developers.pismo.io/pismo-docs/reference/post-create-funds-recovery) endpoint.\n",
        "schema": {
          "type": "string"
        },
        "required": true,
        "example": "53D0F66A-BAB0-49D7-B7DC-807B82AABD8D"
      },
      "UseProviderQuery": {
        "name": "useProvider",
        "in": "query",
        "schema": {
          "type": "string"
        },
        "description": "Search refund in provider? Default is `false`.",
        "example": "true"
      }
    },
    "schemas": {
      "Account": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Account pseudo-identifier",
            "example": "1"
          },
          "owner_id": {
            "type": "string",
            "description": "Reference to holder in persons array",
            "example": "1"
          },
          "participant": {
            "type": "string",
            "description": "Participant ISPB (8 digits) number",
            "pattern": "^\\d{8}$",
            "example": "12345678"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Account opening date (identifies mule accounts)",
            "example": "2024-01-10T10:00:00Z"
          }
        }
      },
      "CreationDatetime": {
        "type": "string",
        "description": "Creation datetime. A RFC 3339 date-time value. For example -  `2023-04-12T23:20:50.52Z`.",
        "format": "date-time",
        "example": "2020-08-13T13:49:03Z"
      },
      "FundsRecoveryId": {
        "type": "string",
        "description": "Funds recovery identifier. \n\nReturned from the [Create funds recovery](https://developers.pismo.io/pismo-docs/reference/post-create-funds-recovery) endpoint.\n",
        "example": "53D0F66A-BAB0-49D7-B7DC-807B82AABD8D"
      },
      "GraphSummary": {
        "type": "object",
        "description": "Graph summary",
        "properties": {
          "total_transactions": {
            "type": "integer",
            "description": "Total number of transactions in the graph",
            "example": 2
          },
          "total_amount": {
            "type": "number",
            "format": "decimal",
            "description": "Total amount of all transactions",
            "example": 1500
          },
          "max_hop_reached": {
            "type": "integer",
            "description": "Maximum hop depth reached in the graph",
            "example": 1
          }
        }
      },
      "message.DetailMessage": {
        "type": "object",
        "properties": {
          "external": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/message.ExternalMessage"
            }
          },
          "parameters": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/message.ParameterMessage"
            }
          },
          "payload": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/message.PayloadMessage"
            }
          }
        }
      },
      "message.ExternalMessage": {
        "required": [
          "code",
          "message"
        ],
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Error code",
            "example": "PBE315"
          },
          "message": {
            "type": "string",
            "description": "Error message",
            "example": "Generic error"
          }
        }
      },
      "message.Message": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Error code",
            "example": "EPDA0001"
          },
          "details": {
            "$ref": "#/components/schemas/message.DetailMessage"
          },
          "message": {
            "type": "string",
            "description": "Error message",
            "example": "User not found"
          }
        }
      },
      "message.ParameterMessage": {
        "type": "object",
        "required": [
          "field",
          "message"
        ],
        "properties": {
          "field": {
            "type": "string",
            "description": "Parameter in error",
            "example": "query parameter"
          },
          "message": {
            "type": "string",
            "description": "Error message",
            "example": "Generic error"
          }
        }
      },
      "message.PayloadMessage": {
        "type": "object",
        "required": [
          "field",
          "message"
        ],
        "properties": {
          "field": {
            "type": "string",
            "description": "Field in error",
            "example": "Entity.field"
          },
          "message": {
            "type": "string",
            "description": "Error messsage",
            "example": "Generic error"
          }
        }
      },
      "Person": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Person pseudo-identifier (protects CPF/CNPJ)",
            "example": "1"
          },
          "type": {
            "$ref": "#/components/schemas/PersonType"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Person record creation date",
            "example": "2025-01-10T10:00:00Z"
          }
        }
      },
      "PersonType": {
        "type": "string",
        "description": "Person type:  \n* `LEGAL_PERSON` - An actual person with legal rights\n* `NATURAL_PERSON` - An entity, such as an organization or company.\n",
        "enum": [
          "LEGAL_PERSON",
          "NATURAL_PERSON"
        ],
        "example": "NATURAL_PERSON"
      },
      "TrackingGraphParameters": {
        "type": "object",
        "description": "Graph parameters. \n\nHigher values for `min_transaction_amount` and lower values for `max_transactions`,`max_hops`, and `hop_window` generate smaller and faster graphs. The opposite generates larger and more complete graphs.\n",
        "required": [
          "min_transaction_amount",
          "max_transactions",
          "hop_window",
          "max_hops"
        ],
        "properties": {
          "min_transaction_amount": {
            "type": "number",
            "description": "Minimum amount in Brazilian reals to include transaction in tracking."
          },
          "max_transactions": {
            "type": "integer",
            "description": "Maximum number of transactions to track"
          },
          "hop_window": {
            "type": "string",
            "description": "The window duration between transactions\n\n  * `PT30M` -  30 minutes\n  * `PT45M` - 45 minutes\n  * `PT1H` - 1 hour\n  * `PT2H` - 2 hours\n  \n  \n",
            "example": "PT2H"
          },
          "max_hops": {
            "type": "integer",
            "description": "Maximum tracking depth, in graph layers.",
            "minimum": 1,
            "maximum": 10,
            "default": 2,
            "example": 5
          }
        }
      },
      "TrackingGraphResponse": {
        "type": "object",
        "properties": {
          "funds_recovery_id": {
            "$ref": "#/components/schemas/FundsRecoveryId"
          },
          "parameters": {
            "$ref": "#/components/schemas/TrackingGraphParameters"
          },
          "persons": {
            "type": "array",
            "description": "Identified people (account holders)",
            "items": {
              "$ref": "#/components/schemas/Person"
            }
          },
          "accounts": {
            "type": "array",
            "description": "Identified transactional accounts",
            "items": {
              "$ref": "#/components/schemas/Account"
            }
          },
          "transactions": {
            "type": "array",
            "description": "PIX transactions that compose the graph",
            "items": {
              "$ref": "#/components/schemas/Transaction"
            }
          },
          "summary": {
            "$ref": "#/components/schemas/GraphSummary"
          },
          "created_at": {
            "$ref": "#/components/schemas/CreationDatetime"
          }
        }
      },
      "Transaction": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Transaction identifier, 32 characters. The **end-to-end ID** of an original transaction,\nwhich begins with `E`, or the **reversal end-to-end ID** of a reversal transaction,\nwhich begins with `D`.\n",
            "pattern": "^[ED][A-Za-z0-9]{31}$",
            "example": "E1234567890123456789012345678901"
          },
          "debtor_account_id": {
            "type": "string",
            "description": "Debtor account ID",
            "example": "156704"
          },
          "creditor_account_id": {
            "type": "string",
            "description": "Creditor account ID",
            "example": "257938"
          },
          "amount": {
            "type": "number",
            "format": "decimal",
            "description": "Original transaction amount",
            "example": 1000
          },
          "refundable_amount": {
            "type": "number",
            "format": "decimal",
            "description": "Amount available for refund (may be less than original)",
            "example": 900
          },
          "settlement_time": {
            "type": "string",
            "format": "date-time",
            "description": "Transaction settlement timestamp. RFC 3339 format.",
            "example": "2025-10-23T09:00:00Z"
          }
        }
      }
    }
  },
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true,
    "samples-enabled": true
  },
  "paths": {
    "/v1/pix/funds-recoveries/{funds_recovery_id}/tracking-graph": {
      "get": {
        "summary": "Get tracking graph [beta]",
        "description": "Get tracking graphs.\n\nRetrieves the tracking graph that maps the chain of subsequent transactions originated from the dispersion of fraudulent funds.\n\nThe graph identifies people, accounts, and transactions involved in the movement of diverted funds.\n\nYou can call this endpoint if you are:\n * The funds recovery creator participant\n * Counterparty participants who received related infraction notifications\n",
        "operationId": "get-refund-recovery",
        "tags": [
          "Funds recovery"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/FundsRecoveryIdPath2"
          },
          {
            "$ref": "#/components/parameters/UseProviderQuery"
          }
        ],
        "responses": {
          "200": {
            "description": "OK - success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TrackingGraphResponse"
                },
                "example": {
                  "graph_id": "graph-uuid-001",
                  "funds_recovery_id": "550e8400-e29b-41d4-a716-446655440000",
                  "parameters": {
                    "min_transaction_amount": 100,
                    "max_transactions": 50,
                    "hop_window": "PT1H",
                    "max_hops": 3
                  },
                  "persons": [
                    {
                      "id": "1",
                      "type": "NATURAL_PERSON",
                      "created_at": "2025-01-10T10:00:00Z"
                    },
                    {
                      "id": "2",
                      "type": "NATURAL_PERSON",
                      "created_at": "2023-05-15T10:00:00Z"
                    }
                  ],
                  "accounts": [
                    {
                      "id": "1",
                      "owner_id": "1",
                      "participant": "12345678",
                      "created_at": "2024-01-10T10:00:00Z"
                    },
                    {
                      "id": "2",
                      "owner_id": "2",
                      "participant": "87654321",
                      "created_at": "2023-05-15T10:00:00Z"
                    }
                  ],
                  "transactions": [
                    {
                      "id": "E1234567890123456789012345678901",
                      "debtor_account_id": "1",
                      "creditor_account_id": "2",
                      "amount": 1000,
                      "refundable_amount": 900,
                      "settlement_time": "2025-10-23T09:00:00Z",
                      "hop": 0
                    },
                    {
                      "id": "E2345678901234567890123456789012",
                      "debtor_account_id": "2",
                      "creditor_account_id": "3",
                      "amount": 500,
                      "refundable_amount": 500,
                      "settlement_time": "2025-10-23T09:05:00Z",
                      "hop": 1
                    }
                  ],
                  "summary": {
                    "total_transactions": 2,
                    "total_amount": 1500,
                    "max_hop_reached": 1
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid ID format",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/message.Message"
                },
                "examples": {
                  "Invalid ID format": {
                    "value": {
                      "code": "EPDA0000",
                      "message": "Invalid funds recovery ID format"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Funds recovery or tracking graph not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/message.Message"
                },
                "examples": {
                  "Recovery not found": {
                    "value": {
                      "code": "EPDA0000",
                      "message": "Funds recovery not found or access denied"
                    }
                  },
                  "Graph not found": {
                    "value": {
                      "code": "EPDA0000",
                      "message": "Tracking graph not found"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```