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 File URI (e.g., file:///workspace/main.py)
Character position (0-indexed)
Include the declaration/definition in results
Response Array of all reference locations File URI where symbol is referenced
Text range of the reference Start position (line, character)
End position (line, character)
Total number of references found
Example Request cURL
Python
JavaScript
TypeScript
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 } }'
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_totalAssignments func = calculate_totalType hints def process(calc: Callable = calculate_total)Decorators @calculate_totalString 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]
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_FOUNDFile doesn’t exist Verify file path INVALID_POSITIONPosition out of bounds Check line/character values NO_SYMBOL_FOUNDNo symbol at position Position cursor on a valid symbol WORKSPACE_NOT_INDEXEDWorkspace still indexing Wait for indexing to complete TIMEOUTSearch 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.
