---
title: "Cancel a collection"
method: DELETE
path: "/collections/{id}"
tags: ["Collections"]
---

# Cancel a collection

`DELETE /collections/{id}`

## Request

- Base URL: `https://api.gmaps.dev/v1`
- URL: `https://api.gmaps.dev/v1/collections/{id}`
- Auth: HTTP bearer

Stop a collection you no longer want. One that has not started yet stops at once and costs nothing. One already running keeps the places that have arrived and the credits they cost; the search in flight finishes, and nothing new starts. A collection that has already ended cannot be cancelled. Needs an API key. Costs no credits.

## Path parameters

- `id` string, uuid, required: The collection's id, as create_collection returned it.

## Response `200`

Cancel a collection

- object
  - `data` object, required
    - `id` string, uuid, required: Our id for the collection. get_collection, list_collection_places, cancel_collection and create_export take it.
    - `kind` 'search' | 'collection', required: `collection` when you asked for it, `search` when a search started it to fill its `limit`.
    - `status` 'queued' | 'running' | 'succeeded' | 'partial' | 'failed' | 'cancelled', required: `queued` while it waits its turn, `running` while it searches, then `succeeded`, `partial`, `failed` or `cancelled`.
    - `stopReason` 'quota' | 'daily_cap' | 'cancelled' | 'engine' | 'empty', nullable, required: Why it stopped short, or found nothing. A credit limit shows here as soon as it is hit, while the search already in flight finishes. Null when it searched the whole area or reached `maxPlaces`.
    - `query` object, required: What you asked for, exactly as it ran, with `maxPlaces` filled in from your plan when you left it out.
      - `keywords` string[], required: What it searched for. One search per term.
      - `geo` union, required: The area, as you gave it: a Brazilian city as location, a lat/lng point with radiusM, a bbox, or a cityIbge with radiusKm.
        - object
          - `location` string, required
        - object
          - `lat` number, required
          - `lng` number, required
          - `radiusM` number, required
        - object
        - object
          - `cityIbge` integer, required
          - `radiusKm` number, required
      - `lang` string, required: The language it searched in. Two letters, such as pt or en.
      - `minRating` number, nullable, required: Only places rated at least this were kept, from 1 to 5. Null when every place was.
      - `maxPlaces` integer, required: It stops after this many places: what you asked for, or the most your plan collects at once.
      - `enrich` string[], required: ["emails"] when it also looks for email addresses, which costs one more credit for each place that has one. Empty when it doesn't.
    - `area` union, required: Where it searched, ready to draw: a lat/lng centre with radiusM in metres, or a bbox as [west, south, east, north]. A city is the circle we searched around its centre. Null for an old collection whose city we can no longer place.
      - object
        - `lat` number, required
        - `lng` number, required
        - `radiusM` integer, required
      - object
    - `squaresTotal` integer, required: How many searches the area takes: one per square of the area, for each term.
    - `squaresCovered` integer, required: How many of those we searched recently enough to reuse. Their places cost nothing.
    - `jobsTotal` integer, required: Batches of searching. Each one covers several squares around one point.
    - `jobsDone` integer, required: How many of those batches have finished.
    - `counts` object, required: What it has delivered so far, and what that cost.
      - `placesDelivered` integer, required: Places handed over so far: always `placesFresh` plus `placesCached`.
      - `placesFresh` integer, required: Places we collected for you just now, either new to us or too old to reuse. Each costs one credit.
      - `placesCached` integer, required: Places we already had saved. They cost nothing.
      - `creditsCharged` integer, required: Credits taken: one per fresh place, plus one per place we found an email for.
      - `creditsRefunded` integer, required: Credits given back. A collection that delivers nothing refunds all of them.
    - `error` object, nullable, required: Why it failed, shaped like any other error. Null unless `status` is `failed`.
      - `code` 'VALIDATION_ERROR' | 'UNAUTHORIZED' | 'INVALID_TOKEN' | 'PLAN_GATE' | 'AUP_REQUIRED' | 'FORBIDDEN' | 'NOT_FOUND' | 'PLACE_NOT_FOUND' | 'COLLECTION_NOT_FOUND' | 'EXPORT_NOT_FOUND' | 'CONFLICT' | 'PAYLOAD_TOO_LARGE' | 'GEO_UNRESOLVED' | 'UPSTREAM_BLOCKED' | 'RATE_LIMIT_EXCEEDED' | 'QUOTA_EXCEEDED' | 'INTERNAL_ERROR' | 'ENGINE_UNAVAILABLE' | 'SERVICE_UNAVAILABLE' | 'BILLING_UNAVAILABLE', required: What went wrong, as a word a program can check.
      - `message` string, required: What went wrong, as a sentence.
      - `messageKey` 'serverErrors.validation' | 'serverErrors.unauthorized' | 'serverErrors.keyInactive' | 'serverErrors.signInRequired' | 'serverErrors.planGateEmails' | 'serverErrors.planGateWebhooks' | 'serverErrors.planGateContact' | 'serverErrors.aupRequired' | 'serverErrors.forbidden' | 'serverErrors.accountSuspended' | 'serverErrors.accountDeletionRequested' | 'serverErrors.accountDeleted' | 'serverErrors.lastStaff' | 'serverErrors.notFound' | 'serverErrors.placeNotFound' | 'serverErrors.placeShortLink' | 'serverErrors.placeLinkNotOne' | 'serverErrors.placeRefUnreadable' | 'serverErrors.collectionNotFound' | 'serverErrors.collectionEnded' | 'serverErrors.collectionPlacesDeleted' | 'serverErrors.exportNotFound' | 'serverErrors.exportNothingYet' | 'serverErrors.exportNothingFound' | 'serverErrors.conflict' | 'serverErrors.payloadTooLarge' | 'serverErrors.geoUnresolved' | 'serverErrors.cityAmbiguous' | 'serverErrors.cityDidYouMean' | 'serverErrors.cityUnknown' | 'serverErrors.cityIbgeUnknown' | 'serverErrors.areaTooLarge' | 'serverErrors.radiusTooLarge' | 'serverErrors.noSearchTerms' | 'serverErrors.tooManyTerms' | 'serverErrors.maxPlacesOverPlan' | 'serverErrors.xlsxTooLarge' | 'serverErrors.keyLimit' | 'serverErrors.subscriptionOpen' | 'serverErrors.checkoutOpen' | 'serverErrors.webhookNotHttps' | 'serverErrors.webhookCredentials' | 'serverErrors.webhookPrivateAddress' | 'serverErrors.webhookNoAddress' | 'serverErrors.webhookDuplicate' | 'serverErrors.webhookUnreachable' | 'serverErrors.webhookTimeout' | 'serverErrors.webhookStatus' | 'serverErrors.webhookRedirect' | 'serverErrors.webhookStopped' | 'serverErrors.webhookOff' | 'serverErrors.upstreamBlocked' | 'serverErrors.rateLimit' | 'serverErrors.quotaMonth' | 'serverErrors.quotaDay' | 'serverErrors.concurrency' | 'serverErrors.internal' | 'serverErrors.engineUnavailable' | 'serverErrors.collectionEngineFailed' | 'serverErrors.serviceUnavailable' | 'serverErrors.billingUnavailable' | 'serverErrors.billingCurrencyUnavailable': `message` as a key, to show it in your reader's language, with `params` filling its blanks.
      - `params` object: The values that fill `messageKey`'s blanks, such as a limit.
      - `details` unknown
    - `queuedAt` string, date-time, required: When we accepted it. ISO 8601 with an offset, as every date here is.
    - `startedAt` string, date-time, nullable, required: When the first search started. Null while it waits its turn.
    - `finishedAt` string, date-time, nullable, required: When it ended. Null while it runs.
    - `cancelRequestedAt` string, date-time, nullable, required: Set the moment you cancel. The search already in flight still finishes.
    - `resultsExpireAt` string, date-time, required: After this, the counts stay but its places can no longer be listed. Export them first.
  - `meta` union
    - object
      - `total` integer, required: Every item that matches, not just this page.
      - `limit` integer, required: The most items a page holds.
      - `offset` integer, required: How many items came before this page.
      - `hasMore` boolean, required: True when another page follows.
    - object
      - `cost` integer, required: Credits this call took.
      - `creditsRemaining` integer, required: Credits left after this call, this month's and bought ones together.
      - `requestId` string, required: This call's id. Send it to support if something went wrong.
      - `cached` boolean: True when this response used only saved results.

## Other responses

- `default`: Any other failure.

---

[API](https://skmtc.dev/gmaps/apis/gmaps-dev.md) · [All operations](https://skmtc.dev/gmaps/apis/gmaps-dev/llms.txt) · [OpenAPI document](https://skmtc.dev/gmaps/apis/gmaps-dev/revisions/0b3459aaf802?raw)