---
ref: tool:salesforce/query-records
name: Query records with SOQL
company: company:salesforce
workflows: [workflow:closed-lost-reengagement]
access: [mcp, cli, api]
tags: [capability:manage-crm, category:crm, has:api, has:cli, has:mcp]
docs: https://developer.salesforce.com/docs/platform/api-rest/guide/resources-query.html
updated: 2026-09-29
---

# Query records with SOQL

Runs a SOQL query and returns the matching records with the fields it selects.

Note: One response holds up to 2,000 records; when there are more, fetch the next batch from `nextRecordsUrl`.

## Set up

Use the first option your agent supports.

### MCP (official, remote)

Add this server to your agent's MCP settings, then sign in when asked.

```json
{ "mcpServers": { "salesforce": { "url": "https://api.salesforce.com/platform/mcp/v1/platform/sobject-mutations" } } }
```

Call the MCP tool `soqlQuery`.

Server URL: https://api.salesforce.com/platform/mcp/v1/platform/sobject-mutations

Note: An admin creates an External Client App and activates the server first. It never deletes records.

### CLI (official)

Install the command and sign in with it, then confirm it runs.

```sh
npm install @salesforce/cli --global
sf --version
```

Run `sf data query`.

Note: Sign in with `sf org login web`; `sf org display` then prints the instance URL and API version.

### API (official)

- Base URL: https://{my_domain}.my.salesforce.com
- Endpoint: `GET /services/data/vXX.X/query`
- Auth: an OAuth access token, sent as `Authorization: Bearer <token>`
- Docs: https://developer.salesforce.com/docs/platform/api-rest/guide/intro-rest.html

Note: `{my_domain}` is your org's My Domain name, and paths carry the API version as `vXX.X`; `sf org display` prints both as Instance Url and Api Version.

Before anything else, confirm access with the cheapest read-only call, like a list or a search. Never send or change anything to test access.

## Rules

- Ask the user before anything that sends messages, costs money, or changes data, and say how many records it touches. One approval covers a batch the user has seen.
- Never print API keys.