Note: This release is in preview. Features described here don’t become generally available until the latest general availability date that Salesforce announces for this release. Before then, and where features are noted as beta, pilot, or developer preview, we can’t guarantee general availability within any particular time frame or at all. Make your purchase decisions only on the basis of generally available products and features.

Query

Runs the specified SOQL query.

When a SOQL query is executed, up to 2,000 records can be returned at a time in a synchronous request. However, to optimize performance, the returned batch can include fewer records than the limit or what's set in the request, based on the size and complexity of records queried. If the total number of results exceeds the limit or the requested number of results, the response contains the first batch of records, a false value for done, and a query locator. You can use the query locator with the Query More Results resource to retrieve the next batch of records.

The response contains the total number of records returned by the Query request (totalSize), a boolean indicating whether there are no more results (done), the URI of the next set of records (nextRecordsUrl), and an array of query result records (records).

Syntax

URI: /services/data/vXX.X/query?q=query

Formats: JSON, XML

HTTP Method: GET

Authentication: Authorization: Bearer token

Parameters

Parameter	Description
q	A SOQL query. To create a valid URI, replace spaces in the query string with a plus sign `+` or with `%20`. For example: `SELECT+Name+FROM+MyObject`. If the SOQL query string is invalid, a MALFORMED_QUERY response is returned.

Example

Example Response Body

1{
2  "totalSize": 3222,
3  "done": false,
4  "nextRecordsUrl": "/services/data/v67.0/query/01gRO0000016PIAYA2-500",
5  "records": [
6    {
7      "attributes": {
8        "type": "Contact",
9        "url": "/services/data/v67.0/sobjects/Contact/003RO0000035WQgYAM"
10      },
11      "Id": "003RO0000035WQgYAM",
12      "Name": "John Smith"
13    },
14    ...
15  ]
16}

Resources for Running SOQL Queries

For an example, see Execute a SOQL Query.
To change the batch size, see Query Options Header.
To get feedback on a query and a report by using the explain parameter, see Get Feedback on Query Performance.
For more information on SOQL in general, see the SOQL and SOSL Reference.

REST API Developer Guide

Query

Syntax

Example

Resources for Running SOQL Queries