---
name: "salesforce_query"
area: "salesforce"
title: "Query Salesforce"
price: "free"
method: "POST"
url: "https://api.conecto.chat/v1/tools/salesforce_query"
mcp_server: "https://api.conecto.chat/mcp/salesforce"
auth: "Authorization: Bearer <conecto_sk_ key>"
docs_url: "https://conecto.chat/tools/salesforce/salesforce_query"
---

# Query Salesforce (`salesforce_query`)

Runs one SOQL SELECT statement and returns up to 200 records.

Run one SOQL SELECT statement in the company's org and get its records, up to 200; more says when there are others. Only reading. Free.

Price: Free up to 1,000,000 reads a month for the whole account, then $0.50 per 10,000 reads. A call that fails costs nothing.

## Use it when

The agent needs records that match conditions: an account's opportunities, open cases.

## Say this to your agent

> What are Hotel Seeblick's latest opportunities?

## Inputs

| Name | Type | Required | Description | Allowed values | Default |
|---|---|---|---|---|---|
| `soql` | string | yes | 10 to 4,000 characters. |  |  |

## Example

Written for Hansen & Voss, a restaurant-equipment wholesaler in Hamburg with 60 staff.

MCP: call `salesforce_query` on the MCP server `https://api.conecto.chat/mcp/salesforce` with these arguments:

```json
{
  "soql": "SELECT Id, Name, StageName, Amount FROM Opportunity WHERE Account.Name = 'Hotel Seeblick' ORDER BY CloseDate DESC LIMIT 5"
}
```

REST:

```bash
curl https://api.conecto.chat/v1/tools/salesforce_query \
  -H "Authorization: Bearer $CONECTO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"soql": "SELECT Id, Name, StageName, Amount FROM Opportunity WHERE Account.Name = '\''Hotel Seeblick'\'' ORDER BY CloseDate DESC LIMIT 5"}'
```

## Response

```json
{
  "call_id": "5f0c8a2e-3b7d-4c1e-9a64-2d8e1f7b0c93",
  "tool": "salesforce_query",
  "status": "succeeded",
  "replayed": false,
  "cost_usd": "$0.00",
  "balance_usd": "$19.75",
  "result": {
    "records": [
      {
        "Id": "0065g00000Xy1AbAAJ",
        "Name": "Combi steamers",
        "StageName": "Proposal",
        "Amount": 18400,
        "CloseDate": "2026-11-09"
      }
    ],
    "total": 1,
    "more": false
  }
}
```

`result`: records, total, and more when there are others.

## Errors

| Code | Status | When | Fix |
|---|---|---|---|
| `not_connected` | 409 | Salesforce isn't connected yet. | Connect it with salesforce_connect. |
| `vendor_rejected` | 502 | Salesforce refused: the app's keys, or the run-as user may not do that. | Give the run-as user the permission the message names. |
| `invalid_input` | 400 | Salesforce refused the query or the fields, or the object or id is not one. | Fix what the message names; field names are API names, like StageName. |

The refusals every tool can give (401 key, 402 balance, 429 limits) are on the errors page: https://conecto.chat/docs/errors.md

## Related

- [salesforce_connect](https://conecto.chat/tools/salesforce/salesforce_connect.md): Connects the company's Salesforce org through its own connected app. Free.
- [salesforce_get](https://conecto.chat/tools/salesforce/salesforce_get.md): One Salesforce record by object and id, with all its fields or the ones named. Free up to 1,000,000 reads a month.
- [salesforce_create](https://conecto.chat/tools/salesforce/salesforce_create.md): Makes a record of any object the run-as user may create. $0.001 a call.
- [salesforce_update](https://conecto.chat/tools/salesforce/salesforce_update.md): Changes a Salesforce record's fields; waits for the owner by default. $0.001 a call.
- [salesforce_disconnect](https://conecto.chat/tools/salesforce/salesforce_disconnect.md): Forgets the connected app's secret; nothing in Salesforce changes. Free.