Get References

curl --request POST \
  --url https://api.example.com/tools/get_references

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/tools/get_references",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/tools/get_references"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/tools/get_references")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

{
  "locations": [
    {
      "uri": "<string>",
      "range": {
        "start": {},
        "end": {}
      }
    }
  ],
  "totalCount": 123
}

POST

tools

get_references

Get References

curl --request POST \
  --url https://api.example.com/tools/get_references

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/tools/get_references",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/tools/get_references"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/tools/get_references")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

{
  "locations": [
    {
      "uri": "<string>",
      "range": {
        "start": {},
        "end": {}
      }
    }
  ],
  "totalCount": 123
}

Overview

Find every place in your workspace where a symbol (function, class, variable, etc.) is referenced. This is essential for understanding symbol usage, refactoring, and impact analysis.

Request

string

required

File URI (e.g., file:///workspace/main.py)

number

required

Line number (0-indexed)

number

required

Character position (0-indexed)

boolean

default:"true"

Include the declaration/definition in results

Response

array

Array of all reference locations

Show Location Object

string

File URI where symbol is referenced

object

Text range of the reference

Show Range

object

Start position (line, character)

object

End position (line, character)

number

Total number of references found

Example Request

curl -X POST https://api.pylancemcp.dev/v1/tools/call \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "get_references",
    "arguments": {
      "uri": "file:///workspace/app/utils.py",
      "line": 8,
      "character": 4,
      "includeDeclaration": true
    }
  }'

from pylance_mcp import Client

client = Client(api_key="YOUR_API_KEY")

references = client.get_references(
    uri="file:///workspace/app/utils.py",
    line=8,
    character=4,
    include_declaration=True
)

print(f"Found {references.total_count} references")
for location in references.locations:
    print(f"  {location.uri}:{location.range.start.line + 1}")

import { PylanceMCP } from '@pylance-mcp/client';

const client = new PylanceMCP({ apiKey: 'YOUR_API_KEY' });

const references = await client.getReferences({
  uri: 'file:///workspace/app/utils.py',
  line: 8,
  character: 4,
  includeDeclaration: true
});

console.log(`Found ${references.totalCount} references`);
references.locations.forEach(location => {
  console.log(`  ${location.uri}:${location.range.start.line + 1}`);
});

import { PylanceMCP, ReferencesRequest } from '@pylance-mcp/client';

const client = new PylanceMCP({ apiKey: process.env.PYLANCE_API_KEY! });

const request: ReferencesRequest = {
  uri: 'file:///workspace/app/utils.py',
  line: 8,
  character: 4,
  includeDeclaration: true
};

const references = await client.getReferences(request);

console.log(`Found ${references.totalCount} references`);
for (const location of references.locations) {
  console.log(`  ${location.uri}:${location.range.start.line + 1}`);
}

Example Response

{
  "locations": [
    {
      "uri": "file:///workspace/app/utils.py",
      "range": {
        "start": { "line": 8, "character": 4 },
        "end": { "line": 8, "character": 19 }
      }
    },
    {
      "uri": "file:///workspace/app/views.py",
      "range": {
        "start": { "line": 42, "character": 12 },
        "end": { "line": 42, "character": 27 }
      }
    },
    {
      "uri": "file:///workspace/app/views.py",
      "range": {
        "start": { "line": 87, "character": 8 },
        "end": { "line": 87, "character": 23 }
      }
    },
    {
      "uri": "file:///workspace/tests/test_utils.py",
      "range": {
        "start": { "line": 15, "character": 16 },
        "end": { "line": 15, "character": 31 }
      }
    }
  ],
  "totalCount": 4
}

Use Cases

Before Refactoring

# Find all uses of calculate_total before renaming or modifying it
def calculate_total(items: List[Item]) -> float:
#   ^^^^^^^^^^^^^^
# Get references: Find 47 uses across 12 files

# Now you can safely refactor knowing the impact

Understand Function Usage

# Where is this helper function actually used?
def format_currency(amount: float) -> str:
    return f"${amount:.2f}"

# Get references: Shows it's used in 3 different views

Find Unused Code

# Is this function still needed?
def legacy_calculation(data: dict) -> int:
    pass

# Get references: 0 results
# Safe to delete!

Track Variable Usage

# Where is this configuration used?
MAX_RETRIES = 5
# ^^^^^^^^^^^
# Get references: Used in retry logic across 8 files

Reference Types

References are found in various contexts:

Context	Example
Function calls	`calculate_total(items)`
Imports	`from utils import calculate_total`
Assignments	`func = calculate_total`
Type hints	`def process(calc: Callable = calculate_total)`
Decorators	`@calculate_total`
String references	Not included (only code references)

Filtering Results

Results are ordered by file path, then by line number within each file.

Include/Exclude Declaration

# With includeDeclaration: true
# Results include:
# 1. def calculate_total(...) [definition]
# 2. calculate_total(items)   [usage 1]
# 3. calculate_total(data)    [usage 2]

# With includeDeclaration: false
# Results include:
# 1. calculate_total(items)   [usage 1]
# 2. calculate_total(data)    [usage 2]

Performance Tips

Large Projects: First reference search may take 1-2 seconds while indexing workspace

Cache Results: Reference locations don’t change unless code changes

Use Filters: Exclude test files if you only care about production usage

Analyzing Results

Group references by file to understand impact:

from collections import defaultdict

references_by_file = defaultdict(list)
for location in references.locations:
    file_path = location.uri.split('/')[-1]
    references_by_file[file_path].append(location)

# Show which files use this symbol most
for file, refs in sorted(references_by_file.items(), 
                         key=lambda x: len(x[1]), 
                         reverse=True):
    print(f"{file}: {len(refs)} references")

Error Responses

Code	Reason	Solution
`FILE_NOT_FOUND`	File doesn’t exist	Verify file path
`INVALID_POSITION`	Position out of bounds	Check line/character values
`NO_SYMBOL_FOUND`	No symbol at position	Position cursor on a valid symbol
`WORKSPACE_NOT_INDEXED`	Workspace still indexing	Wait for indexing to complete
`TIMEOUT`	Search took too long	Try narrowing search scope

Rate Limits

Tier	Requests/Hour	Requests/Day	Max Results
Free	10	50	100
Hobby	250	2,500	1,000
Pro	2,500	25,000	10,000
Enterprise	Unlimited	Unlimited	Unlimited

Large projects may return thousands of references. Consider pagination for better performance.

Get Definition

Find where a symbol is defined

Rename Symbol

Safely rename across all references

Get Hover

See symbol documentation

Get Diagnostics

Find errors in your code

Get Started

Core Concepts

Guides

API Reference

Deployment

Get References

Overview

Request

Response

Example Request

Example Response

Use Cases

Before Refactoring

Understand Function Usage

Find Unused Code

Track Variable Usage

Reference Types

Filtering Results

Include/Exclude Declaration

Performance Tips

Analyzing Results

Error Responses

Rate Limits

Get Definition

Rename Symbol

Get Hover

Get Diagnostics

​Overview

​Request

​Response

​Example Request

​Example Response

​Use Cases

​Before Refactoring

​Understand Function Usage

​Find Unused Code

​Track Variable Usage

​Reference Types

​Filtering Results

​Include/Exclude Declaration

​Performance Tips

​Analyzing Results

​Error Responses

​Rate Limits

​Related Tools

Get Definition

Rename Symbol

Get Hover

Get Diagnostics

Overview

Request

Response

Example Request

Example Response

Use Cases

Before Refactoring

Understand Function Usage

Find Unused Code

Track Variable Usage

Reference Types

Filtering Results

Include/Exclude Declaration

Performance Tips

Analyzing Results

Error Responses

Rate Limits

Related Tools