# Return One Shard Key Analysis for One Cluster **GET /api/atlas/v2/groups/{groupId}/clusters/{clusterName}/shardKeyAnalyses/{analysisId}** Returns one completed shard key analysis for the specified cluster. This resource exists only once the operation that produced it has succeeded and reports no operation status of its own. MongoDB Cloud retains an analysis for 30 days. ## Role requirements - Project Data Access Admin - Project Data Access Read Only - Project Data Access Read Write - Project Stream Processing Owner ## Servers - https://cloud.mongodb.com: https://cloud.mongodb.com () ## Authentication methods - Service accounts - Digest auth ## Parameters ### Path parameters - **groupId** (string) Unique 24-hexadecimal digit string that identifies your project. Use the [/groups](#tag/Projects/operation/listProjects) endpoint to retrieve all projects to which the authenticated user has access. **NOTE**: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups. - **clusterName** (string) Human-readable label that identifies the cluster with the shard key analysis you want to return. - **analysisId** (string) Unique 24-hexadecimal digit string that identifies the shard key analysis to return. ### Query parameters - **envelope** (boolean) Flag that indicates whether Application wraps the response in an `envelope` JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body. - **pretty** (boolean) Flag that indicates whether the response body should be in the prettyprint format. ## Responses ### 200 OK #### Headers - **RateLimit-Limit** () The maximum number of requests that a user can make within a specific time window. - **RateLimit-Remaining** () The number of requests remaining in the current rate limit window before the limit is reached. #### Body: application/vnd.atlas.2025-03-12+json (object) - **avgDocSizeBytes** (integer(int64)) Average size of one document in the collection, in bytes. - **correlationCoefficient** (number(double)) Correlation between the candidate shard key and the order in which documents were inserted, from `-1` to `1`. Values near `1` or `-1` indicate a monotonically changing key, which directs all inserts to one shard. This parameter is absent when the shard key has no supporting index or the collection is clustered, in which case MongoDB Cloud does not compute it. - **createdAt** (string(date-time)) Date and time when this shard key analysis was requested (ISO 8601 format in UTC). This is when the analysis was submitted, not when it completed; the completion time is the `updatedAt` of the operation that produced it. - **expiresAt** (string(date-time)) Date and time when MongoDB Cloud stops returning this shard key analysis (ISO 8601 format in UTC). Reads after this time return an HTTP 404 status. - **id** (string) Unique 24-hexadecimal digit string that identifies this shard key analysis. This is the same identifier as the `operationId` of the operation that produced it. - **isUnique** (boolean) Flag that indicates whether the index supporting the candidate shard key enforces a uniqueness constraint. - **monotonicity** (string) Whether the shard key value increases or decreases with the order in which documents were inserted. A monotonically changing shard key directs all inserts to one shard. `UNKNOWN` indicates that MongoDB Cloud could not determine monotonicity, which happens when the shard key has no supporting index or the collection is clustered. - **mostCommonValues** (array[object]) Shard key values that occur most frequently in the sampled documents, with how often each occurs. MongoDB Cloud returns this parameter only to callers that can read the collection's data, because it carries values out of the collection rather than statistics about them. - **namespace** (string) Combination of the database and collection that was analyzed, written as `.`. - **note** (string) Guidance from MongoDB on how to interpret the metrics in this analysis. This parameter is absent when the analysis carries no guidance. - **numDistinctValues** (integer(int64)) Number of distinct values that the candidate shard key takes across the sampled documents. A value close to `numDocsSampled` indicates high cardinality, which distributes documents well. - **numDocsSampled** (integer(int64)) Number of documents that MongoDB Cloud sampled to compute these metrics. - **numDocsTotal** (integer(int64)) Number of documents in the collection. - **numOrphanDocs** (integer(int64)) Number of orphaned documents in the collection. This parameter is absent for collections that have none. - **percentageOfMultiShardReads** (number(double)) Percentage of sampled reads that the candidate shard key would route to more than one shard but not to every shard. - **percentageOfMultiShardWrites** (number(double)) Percentage of sampled writes that the candidate shard key would route to more than one shard but not to every shard. - **percentageOfScatterGatherReads** (number(double)) Percentage of sampled reads that the candidate shard key would broadcast to every shard. Lower is better. - **percentageOfScatterGatherWrites** (number(double)) Percentage of sampled writes that the candidate shard key would broadcast to every shard. Lower is better. - **percentageOfSingleShardReads** (number(double)) Percentage of sampled reads that the candidate shard key would route to exactly one shard. Higher is better. - **percentageOfSingleShardWrites** (number(double)) Percentage of sampled writes that the candidate shard key would route to exactly one shard. Higher is better. - **rawOutput** (string) Unmodified result of the `analyzeShardKey` command, as a JSON string. Its content tracks the MongoDB server version of the analyzed cluster rather than the version of this resource, so members outside the parameters above may appear or change without a new resource version. Do not parse it as a stable contract. `mostCommonValues` is removed from it for callers that cannot read the collection's data. This parameter is absent if MongoDB Cloud could not serialize the command result, which costs the raw view but not the analysis. - **readSampleSize** (object) Number of sampled read operations that MongoDB Cloud used to compute the read distribution, broken down by the command that issued them. - **shardKey** (array[object]) Candidate shard key that was analyzed, given as one object per shard key field in the order the fields form the key. This parameter is absent when MongoDB Cloud has no shard key recorded for the analysis. - **writeSampleSize** (object) Number of sampled write operations that MongoDB Cloud used to compute the write distribution, broken down by the command that issued them. ### 400 Bad Request. #### Body: application/json (object) - **badRequestDetail** (object) Bad request detail. - **detail** (string | null) Describes the specific conditions or reasons that cause each type of error. - **error** (integer(int32)) HTTP status code returned with this error. - **errorCode** (string) Application error code returned with this error. - **parameters** (array[object]) Parameters used to give more information about the error. - **reason** (string | null) Application error message returned with this error. ### 401 Unauthorized. #### Body: application/json (object) - **badRequestDetail** (object) Bad request detail. - **detail** (string | null) Describes the specific conditions or reasons that cause each type of error. - **error** (integer(int32)) HTTP status code returned with this error. - **errorCode** (string) Application error code returned with this error. - **parameters** (array[object]) Parameters used to give more information about the error. - **reason** (string | null) Application error message returned with this error. ### 403 Forbidden. #### Body: application/json (object) - **badRequestDetail** (object) Bad request detail. - **detail** (string | null) Describes the specific conditions or reasons that cause each type of error. - **error** (integer(int32)) HTTP status code returned with this error. - **errorCode** (string) Application error code returned with this error. - **parameters** (array[object]) Parameters used to give more information about the error. - **reason** (string | null) Application error message returned with this error. ### 404 Not Found. #### Body: application/json (object) - **badRequestDetail** (object) Bad request detail. - **detail** (string | null) Describes the specific conditions or reasons that cause each type of error. - **error** (integer(int32)) HTTP status code returned with this error. - **errorCode** (string) Application error code returned with this error. - **parameters** (array[object]) Parameters used to give more information about the error. - **reason** (string | null) Application error message returned with this error. ### 429 Too Many Requests. #### Headers - **RateLimit-Limit** () The maximum number of requests that a user can make within a specific time window. - **RateLimit-Remaining** () The number of requests remaining in the current rate limit window before the limit is reached. - **Retry-After** () The minimum time you should wait, in seconds, before retrying the API request. This header might be returned for 429 or 503 error responses. #### Body: application/json (object) - **badRequestDetail** (object) Bad request detail. - **detail** (string | null) Describes the specific conditions or reasons that cause each type of error. - **error** (integer(int32)) HTTP status code returned with this error. - **errorCode** (string) Application error code returned with this error. - **parameters** (array[object]) Parameters used to give more information about the error. - **reason** (string | null) Application error message returned with this error. ### 500 Internal Server Error. #### Body: application/json (object) - **badRequestDetail** (object) Bad request detail. - **detail** (string | null) Describes the specific conditions or reasons that cause each type of error. - **error** (integer(int32)) HTTP status code returned with this error. - **errorCode** (string) Application error code returned with this error. - **parameters** (array[object]) Parameters used to give more information about the error. - **reason** (string | null) Application error message returned with this error. [Powered by Bump.sh](https://bump.sh)