> ## Documentation Index
> Fetch the complete documentation index at: https://chainpatrol-mintlify-8989fae6.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Takedown Success Rate
> Get the share of takedowns that ended in a removal, broken down by asset type, for a date range. The range bounds when a takedown was first submitted to a provider, so takedowns opened but never filed are excluded; outcomes are read as of now, and takedowns still being worked count against the rate.
## Overview
Get the share of your organization's takedowns that ended in a removal, broken down by
asset type, for a date range. Use this endpoint to see how often a filed takedown
actually results in the threat coming down, and which asset types resolve most
reliably.
This endpoint is gated behind the `takedown-success-rate` feature flag on a
per-organization basis. If the flag is not enabled for your organization, the API
returns a 403 Forbidden error. Contact ChainPatrol to enable access. The same flag
controls the Takedown Success Rate chart on the dashboard Metrics page.
## How takedowns are counted
* **First-filing cohort** — A takedown enters the cohort based on when it was first
submitted to a provider. The date range filters on that first filing, not on when
the takedown was opened or completed. This is different from the takedown-time
metrics, which key on completion.
* **Never-filed takedowns are excluded** — Takedowns that were opened but never
submitted to a provider do not count toward the denominator. The metric answers
"when a takedown is filed, does the threat come down?", so internal triage decisions
are left out.
* **Re-filed takedowns stay in their original window** — Because the cohort keys on
the first filing, a takedown that is filed again later cannot drift between
reporting periods.
* **Outcomes are read as of now** — The date range bounds the filing, but each
takedown's current status determines the outcome. A recent cohort can read low
simply because its cases have not had time to resolve. Use `stillOpen` to see how
much of the denominator is unfinished rather than failed.
## Response fields
Each entry in `byAssetType` covers one asset type, sorted descending by `submitted`.
Asset types use the same enum names as the rest of the v2 API (for example
`GOOGLE_FORM`).
* `submitted` — takedowns whose first provider filing fell in the range.
* `completed` — of those, how many ended in a completed takedown.
* `stillOpen` — of those, how many have not yet reached an outcome.
* `successRate` — `completed / submitted`, from 0 to 1. Still-open takedowns count
against this rate.
* `resolvedSuccessRate` — `completed / (submitted - stillOpen)`, from 0 to 1, or
`null` when nothing in the group has resolved yet. This rate only considers
takedowns that reached an outcome, so it is higher than `successRate` whenever work
is still outstanding.
## Date handling
* `startDate` and `endDate` are both optional. Omit them to include every takedown
ever filed.
* Date-only values (`YYYY-MM-DD`) are interpreted in UTC. `startDate` begins at
midnight UTC and `endDate` covers the whole day (through 23:59:59.999 UTC). Pass a
full ISO 8601 timestamp for a precise cut-off.
## Filtering
The optional filters match the other takedown metrics endpoints:
* `blockLabel` — only include assets blocked with this review label, for example
`"Brand Impersonation"`.
* `brandType` — only include assets belonging to brands of this type (`INDIVIDUAL`,
`ORGANIZATION`, or `PRODUCT`).
* `countryCodes` — only include assets scanned from these ISO 3166-1 alpha-2
countries.
* `brandIds` — only include assets belonging to these brands.
## Example request
```bash theme={null}
curl --request POST \
--url https://app.chainpatrol.io/api/v2/metrics/takedown-success-rate \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: ' \
--data '{
"slug": "your-org-slug",
"startDate": "2026-07-01",
"endDate": "2026-07-31"
}'
```
## Example response
```json theme={null}
{
"byAssetType": [
{
"assetType": "URL",
"submitted": 120,
"completed": 95,
"stillOpen": 15,
"successRate": 0.7916666666666666,
"resolvedSuccessRate": 0.9047619047619048
},
{
"assetType": "TWITTER",
"submitted": 40,
"completed": 28,
"stillOpen": 10,
"successRate": 0.7,
"resolvedSuccessRate": 0.9333333333333333
}
]
}
```
## Using the JavaScript SDK
The ChainPatrol JavaScript SDK exposes this endpoint as
`getMetricsTakedownSuccessRate`. The SDK accepts date-only strings and widens a
date-only `endDate` to cover the full UTC day before sending the request.
```typescript theme={null}
import { ChainPatrolApiClient, staticApiKey } from "@chainpatrol/sdk/api";
const client = new ChainPatrolApiClient({
credential: staticApiKey(""),
});
const { byAssetType } = await client.getMetricsTakedownSuccessRate({
slug: "your-org-slug",
startDate: "2026-07-01",
endDate: "2026-07-31",
});
for (const row of byAssetType) {
console.log(row.assetType, row.successRate, row.stillOpen);
}
```
## OpenAPI
````yaml POST /metrics/takedown-success-rate
openapi: 3.0.3
info:
title: ChainPatrol External API - OpenAPI 3.0
description: ChainPatrol External API documentation
version: 2.0.0
servers:
- url: https://app.chainpatrol.io/api/v2
security: []
tags:
- name: asset
- name: report
externalDocs:
url: https://chainpatrol.com/docs
paths:
/metrics/takedown-success-rate:
post:
tags:
- metrics
summary: Get organization takedown success rate by asset type
description: >-
Get the share of takedowns that ended in a removal, broken down by asset
type, for a date range. The range bounds when a takedown was first
submitted to a provider, so takedowns opened but never filed are
excluded; outcomes are read as of now, and takedowns still being worked
count against the rate.
operationId: metricsTakedownSuccessRate
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
slug:
type: string
minLength: 1
description: Organization slug
startDate:
type: string
description: >-
Only include takedowns first submitted to a provider on or
after this date. A date-only value (YYYY-MM-DD) starts at
midnight UTC
endDate:
type: string
description: >-
Only include takedowns first submitted to a provider on or
before this date. A date-only value (YYYY-MM-DD) covers the
whole day in UTC; pass a full timestamp for a precise
cut-off
blockLabel:
type: string
description: >-
Only include assets blocked with this review label, e.g.
"Brand Impersonation", "Employee Impersonation" or
"Targeting Org Users"
brandType:
type: string
enum:
- INDIVIDUAL
- ORGANIZATION
- PRODUCT
description: Only include assets belonging to brands of this type
countryCodes:
type: array
items:
type: string
minLength: 2
maxLength: 2
description: >-
Only include assets scanned from these ISO 3166-1 alpha-2
countries
brandIds:
type: array
items:
type: integer
minimum: 0
exclusiveMinimum: true
description: Only include assets belonging to these brands
required:
- slug
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
byAssetType:
type: array
items:
type: object
properties:
assetType:
type: string
enum:
- URL
- PAGE
- ADDRESS
- DISCORD
- LINKEDIN
- TWITTER
- FACEBOOK
- YOUTUBE
- REDDIT
- TELEGRAM
- GOOGLE_APP_STORE
- APPLE_APP_STORE
- AMAZON_APP_STORE
- MICROSOFT_APP_STORE
- TIKTOK
- INSTAGRAM
- THREADS
- MEDIUM
- CHROME_WEB_STORE
- MOZILLA_ADDONS
- OPERA_ADDONS
- EMAIL
- PATREON
- OPENSEA
- FARCASTER
- IPFS
- GOOGLE_FORM
- WHATSAPP
- DISCORD_USER
- QUORA
- GITHUB
- TEACHABLE
- SUBSTACK
- DEBANK
- TAWK_TO
- JOTFORM
- PRIMAL
- BLUESKY
- SNAPCHAT
- DESO
- PINTEREST
- FLICKR
- GALXE
- VELOG
- NPM
- PYPI
- HEX
- DOCKER_HUB
- VOCAL_MEDIA
- TECKFINE
- TENDERLY
- HACKMD
- ETSY
- ZAZZLE
- BASENAME
- BILIBILI_TV
- VIMEO
- DAILYMOTION
- PHONE_NUMBER
- SLACK
- CALENDLY
- NGROK
- RARIBLE
- RUST_PACKAGE
- FLATHUB
- VIDLII
- VEVIOZ
- ISSUU
- SOUNDCLOUD
- ZAPPER
- REDNOTE
- SAMSUNG_APP_STORE
- HUAWEI_APP_STORE
- XIAOMI_APP_STORE
- TENCENT_APP_STORE
- OPPO_APP_STORE
- VIVO_APP_STORE
- F_DROID
- GOOGLE_AD
- BING_AD
- TWITCH
- BEHANCE
- ZORA
- META_AD
- SIGNAL
- DEVIANTART
- BANDCAMP
- ARCHIVE_ORG
- FIVE_HUNDRED_PX
- LUMA
- SMARTMONEYMATCH
- APK_GOLD
description: Asset type the takedowns were filed against
submitted:
type: number
description: >-
Takedowns whose first submission to a provider fell
in the range
completed:
type: number
description: Of those, how many ended in a takedown
stillOpen:
type: number
description: Of those, how many have not yet reached an outcome
successRate:
type: number
description: >-
completed / submitted, 0-1. Still-open takedowns
count against it
resolvedSuccessRate:
type: number
nullable: true
description: >-
completed / (submitted - stillOpen), 0-1, or null
when nothing has resolved yet. Higher than
successRate whenever work is still outstanding
required:
- assetType
- submitted
- completed
- stillOpen
- successRate
- resolvedSuccessRate
description: >-
Takedown success rate, one entry per asset type,
descending by number submitted
required:
- byAssetType
'400':
description: Invalid input data
content:
application/json:
schema:
$ref: '#/components/schemas/error.BAD_REQUEST'
'401':
description: Authorization not provided
content:
application/json:
schema:
$ref: '#/components/schemas/error.UNAUTHORIZED'
'403':
description: Insufficient access
content:
application/json:
schema:
$ref: '#/components/schemas/error.FORBIDDEN'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/error.INTERNAL_SERVER_ERROR'
security:
- ApiKey: []
components:
schemas:
error.BAD_REQUEST:
type: object
properties:
message:
type: string
description: The error message
example: Invalid input data
code:
type: string
description: The error code
example: BAD_REQUEST
issues:
type: array
items:
type: object
properties:
message:
type: string
required:
- message
description: An array of issues that were responsible for the error
example: []
required:
- message
- code
title: Invalid input data error (400)
description: The error information
example:
code: BAD_REQUEST
message: Invalid input data
issues: []
error.UNAUTHORIZED:
type: object
properties:
message:
type: string
description: The error message
example: Authorization not provided
code:
type: string
description: The error code
example: UNAUTHORIZED
issues:
type: array
items:
type: object
properties:
message:
type: string
required:
- message
description: An array of issues that were responsible for the error
example: []
required:
- message
- code
title: Authorization not provided error (401)
description: The error information
example:
code: UNAUTHORIZED
message: Authorization not provided
issues: []
error.FORBIDDEN:
type: object
properties:
message:
type: string
description: The error message
example: Insufficient access
code:
type: string
description: The error code
example: FORBIDDEN
issues:
type: array
items:
type: object
properties:
message:
type: string
required:
- message
description: An array of issues that were responsible for the error
example: []
required:
- message
- code
title: Insufficient access error (403)
description: The error information
example:
code: FORBIDDEN
message: Insufficient access
issues: []
error.INTERNAL_SERVER_ERROR:
type: object
properties:
message:
type: string
description: The error message
example: Internal server error
code:
type: string
description: The error code
example: INTERNAL_SERVER_ERROR
issues:
type: array
items:
type: object
properties:
message:
type: string
required:
- message
description: An array of issues that were responsible for the error
example: []
required:
- message
- code
title: Internal server error error (500)
description: The error information
example:
code: INTERNAL_SERVER_ERROR
message: Internal server error
issues: []
securitySchemes:
ApiKey:
type: apiKey
in: header
name: X-API-KEY
description: >-
Your API key. This is required by most endpoints to access our API
programatically. Reach out to us at
[support@chainpatrol.io](mailto:support@chainpatrol.io?subject=Re:%20API%20Key%20for%20SDK&body=Company:%20%0AName:%20%0APurpose:%20)
to get an API key for your use.
````