> ## Documentation Index > Fetch the complete documentation index at: https://docs.govly.com/llms.txt > Use this file to discover all available pages before exploring further. # Aggregate awards by one dimension > Break down the awards matching the same query and filters as search_awards by one dimension, with a count and summed award, obligated, and paid amounts per group. obligatedAmount is the spend figure; awardAmount includes contract ceilings, so a vehicle counts in full. Unless meta.timedOut is true, meta.total is the exact number of awards matched (search_awards's total stops at 10,000) and meta.otherCount is how many of those are not in the returned groups, including awards with no value for the grouping (no contract vehicle, set-aside, or funder on record). To look inside a known agency, set buyerNames to that agency and group by recipient. Grouping by buyer or funder can mix offices and agencies; it does not produce an agency ranking. ## OpenAPI ````yaml /openapi/tools-v1.yaml post /api/tools/v1/awards/aggregate openapi: 3.1.0 info: title: Govly Tools API version: 1.0.0-alpha description: > ALPHA / UNSTABLE: This API is still in active development. Endpoint behavior, request fields, response fields, error codes, and operation names may change before the Tools API is declared stable. REST-callable tool surface for agent and automation workflows. Agents are the primary consumer, but integrations can be built on this API. Responses are JSON for typed clients; MCP tools may render action results into text-oriented formats separately. Validating requests: validate against this schema in your client before sending. Govly ignores a request field it does not recognize rather than rejecting it, so a misspelled filter name is not applied — the response returns 200 with a broader result set than you intended, and nothing marks the difference. Where a request body declares `additionalProperties: false`, strict client-side validation is what catches that. Fields sent with the wrong type are rejected with 400 on most endpoints; validate types in your client too rather than relying on it. Rate limits: each resource (for example awards, opportunities, or workspaces) allows 70 requests per minute per user. Exceeding it returns 429 with the standard error envelope, `code: rate_limited`, and a `Retry-After` header. Keys sent in the `X-API-KEY` header are also subject to the Enterprise API limit of 300 requests per minute per key; see the Rate Limits page. servers: - url: https://app.govly.com security: - bearerApiKey: [] - headerApiKey: [] tags: - name: Opportunities description: Search, fetch, and inspect Govly opportunity records. - name: Awards description: Search and inspect awarded government contracts. - name: Contacts description: Search and inspect government points of contact. - name: Signals description: Search clustered procurement and market intelligence signals. - name: Places description: Resolve place names to canonical Govly Place ids. - name: Product Catalogs description: List government contract price lists and search their line items. - name: Workspaces description: Create, update, and inspect opportunity workspaces. - name: Organization Users description: Discover the members of your organization and their account status. - name: Workspace Members description: Add users and teams to workspaces. - name: File Attachments description: >- Attach new or existing files through a signed Govly transfer or an authorized reference. - name: Workspace Attachments description: List and upload workspace attachments. - name: Workspace Comments description: Post comments to workspaces. - name: Organization Labels description: List, create, rename, recolor, and delete the organization's labels. - name: Record Labels description: >- Apply and remove the organization's labels on opportunities, awards, contacts, and workspaces. - name: Follows description: Follow opportunities and related workspace activity. - name: Shares description: Share opportunities, awards, and contacts with colleagues by email. - name: Saved Searches description: List saved opportunity searches and cached matches. - name: Documents description: >- Read document representations and request temporary original-file downloads. - name: Quote Submissions description: >- Inspect quote submission requirements, submit quotes, and poll submission status. - name: Inbox description: Read and triage the authenticated user's matched inbox items. paths: /api/tools/v1/awards/aggregate: post: tags: - Awards summary: Aggregate awards by one dimension description: > Break down the awards matching the same query and filters as search_awards by one dimension, with a count and summed award, obligated, and paid amounts per group. obligatedAmount is the spend figure; awardAmount includes contract ceilings, so a vehicle counts in full. Unless meta.timedOut is true, meta.total is the exact number of awards matched (search_awards's total stops at 10,000) and meta.otherCount is how many of those are not in the returned groups, including awards with no value for the grouping (no contract vehicle, set-aside, or funder on record). To look inside a known agency, set buyerNames to that agency and group by recipient. Grouping by buyer or funder can mix offices and agencies; it does not produce an agency ranking. operationId: aggregate_awards requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - groupBy properties: groupBy: type: string enum: - recipient - buyer - funder - contractVehicle - setAside description: >- Dimension to group by: recipient (vendor); buyer or funder (the most specific buying or funding organization on the award, usually a contracting or funding office with the agency as a fallback, so one list can mix levels; not an agency ranking, use buyerNames to look inside one agency); contractVehicle; or setAside. orderBy: type: string enum: - count - obligatedAmount - awardAmount - paidAmount default: count description: >- Which groups are returned and in what order: the most awards (count) or the largest summed dollars. A "by dollars" question must use a dollar order, since a count-ordered result can omit a group whose dollars come from a few large awards. limit: type: integer default: 10 description: Groups to return. Values above 50 are clamped to 50. query: type: string description: >- Search text. Supports keywords, quoted phrases, and boolean operators such as AND, OR, and NOT. searchType: type: string enum: - fed - sled - international description: > Market type. Defaults to the authenticated user's market focus (fed or sled). sled and international require the matching organization subscription. dateRange: type: array items: type: string minItems: 2 maxItems: 2 description: >- Filter by award action dates as [start, end] in ISO 8601 format. Searches all time when omitted. recipientNames: type: array items: type: string description: >- Filter to awards won by any of these recipient (vendor) names. buyerNames: type: array items: type: string description: >- Filter to awards bought by any of these government buyer names. funderNames: type: array items: type: string description: >- Filter to awards funded by any of these government funder names. naics: type: array items: type: string description: NAICS codes to filter by, such as 334111. psc: type: array items: type: string description: Product or service codes (PSC) to filter by. amountRange: type: array items: type: number minItems: 2 maxItems: 2 description: Filter by award amount as [minimum, maximum]. placeIds: type: array items: type: string description: >- Filter to awards in any of these canonical place ids from POST /api/tools/v1/places/search or /places/list. Ids match at any administrative level (state, county, city, ZIP, school district, military installation). placeIdsNone: type: array items: type: string description: Exclude awards in any of these canonical place ids. responses: '200': description: Grouped counts and dollar sums content: application/json: schema: $ref: '#/components/schemas/AwardAggregateResponse' '400': $ref: '#/components/responses/Error' '401': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' '422': $ref: '#/components/responses/Error' '429': $ref: '#/components/responses/RateLimited' components: schemas: AwardAggregateResponse: type: object required: - data - meta properties: data: type: array description: Groups ordered by the requested orderBy, largest first. items: $ref: '#/components/schemas/AwardAggregateBucket' meta: $ref: '#/components/schemas/AwardAggregateMeta' AwardAggregateBucket: type: object required: - key - count - awardAmount - obligatedAmount - paidAmount properties: key: type: string description: >- The group's indexed display name (vendor, buying or funding organization, contract vehicle, or set-aside). count: type: integer description: Awards in the group. awardAmount: type: number description: >- Summed award amount. Includes contract ceilings, so a vehicle counts in full. obligatedAmount: type: number description: Summed obligated amount. The figure to use for spend. paidAmount: type: number description: Summed paid amount. AwardAggregateMeta: type: object required: - total - groupBy - orderBy - limit - otherCount - countErrorUpperBound - timedOut - searchType properties: total: type: integer description: > Number of awards matched by the query and filters, exact unless timedOut is true. Unlike search_awards, this total is not capped at 10,000. groupBy: type: string enum: - recipient - buyer - funder - contractVehicle - setAside orderBy: type: string enum: - count - obligatedAmount - awardAmount - paidAmount limit: type: integer description: The bucket cap applied, after clamping. otherCount: type: integer description: > Matched awards not represented in data: those outside the top groups plus those with no value for the grouping field. countErrorUpperBound: type: integer description: > Group counts and sums are computed per index shard and merged. With orderBy count, a returned group's count can be under-counted by at most this many awards (0 means exact). With a dollar orderBy each shard contributes a wide candidate set, so the ranking is accurate for result sets in the hundreds; this field reads -1 when the error cannot be bounded and 0 when every shard returned all of its groups. total is exact unless timedOut is true. timedOut: type: boolean description: > True when Elasticsearch stopped at its time limit and returned a partial result; counts and sums may then be incomplete. searchType: type: string enum: - fed - sled - international description: >- Market actually searched, including the value defaulted from the user's market focus. ErrorEnvelope: type: object required: - errors properties: errors: type: array items: type: object required: - status - code - title - detail properties: status: type: string code: type: string title: type: string detail: type: string source: type: object properties: pointer: type: string RateLimitError: type: object required: - error properties: error: type: string responses: Error: description: Error response content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' RateLimited: description: > Too many requests. Two limiters can produce this status and they use different bodies. The per-user limit of 70 requests per minute for each resource returns the standard error envelope with `code: rate_limited` and a `Retry-After` header. Keys sent in the `X-API-KEY` header are also subject to the Enterprise API limit of 300 requests per minute per key, which returns the plain `error` form with `Retry-After` and the `X-RateLimit-*` headers. Clients should accept either body. headers: Retry-After: description: Seconds to wait before retrying. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/ErrorEnvelope' - $ref: '#/components/schemas/RateLimitError' securitySchemes: bearerApiKey: type: http scheme: bearer bearerFormat: API key headerApiKey: type: apiKey in: header name: X-API-KEY ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.