> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dune.com/llms.txt
> Use this file to discover all available pages before exploring further.
# List Contract Submissions
> List the contract decoding submissions made by your account
Minimum required API key scope: `Read`. Lists the submissions of the user who created the API key.
## Description
Returns the contract decoding submissions made by the user who created the API key, newest first. Use it to track submissions made through [Submit Contracts for Decoding](./decode) or the Dune UI.
## Statuses
| Status | Meaning |
| -------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `pending` | Queued; the decoding pipeline picks it up within about a minute. |
| `approved` | Validated and about to be decoded. |
| `processed` | Decoded tables are available in the Data Explorer. |
| `needs_manual_review` | Waiting for a Dune team member. Always the case for upgrades, renames, deletions, and protected namespaces. |
| `rejected` | Not accepted; `comment` explains why. |
| `in_progress`, `cancelled` | Intermediate and terminal states set during manual handling. |
## Filtering
Combine any of `blockchain_name`, `address`, `project_name`, `contract_name`, and `status`. Filters are ANDed together.
## Pagination
Results are paged with an opaque cursor. Request a page with `limit` (default 50, maximum 250). When more results exist the response includes `next_cursor`; pass it back as the `cursor` parameter to fetch the next page. `total` is the number of submissions matching the filters across all pages.
## Pricing
This is a metadata endpoint and does not consume credits.
## Related Endpoints
* [Submit Contracts for Decoding](./decode) - Submit a batch of contracts
```bash cURL theme={null}
curl -X GET "https://api.dune.com/api/v1/contracts/submissions?blockchain_name=ethereum&status=pending&limit=20" \
-H "X-DUNE-API-KEY: YOUR_API_KEY"
```
```python Python theme={null}
import requests
url = "https://api.dune.com/api/v1/contracts/submissions"
headers = {"X-DUNE-API-KEY": "YOUR_API_KEY"}
params = {"blockchain_name": "ethereum", "status": "pending", "limit": 20}
while True:
page = requests.get(url, params=params, headers=headers).json()
for submission in page["submissions"]:
print(submission["id"], submission["status"])
if "next_cursor" not in page:
break
params["cursor"] = page["next_cursor"]
```
```javascript JavaScript theme={null}
const url = 'https://api.dune.com/api/v1/contracts/submissions';
const params = new URLSearchParams({
blockchain_name: 'ethereum',
status: 'pending',
limit: 20
});
const response = await fetch(`${url}?${params}`, {
headers: { 'X-DUNE-API-KEY': 'YOUR_API_KEY' }
});
const data = await response.json();
console.log(data.submissions, data.next_cursor);
```
```json Example Response theme={null}
{
"submissions": [
{
"id": "0b1e4c2a-7d3f-4e5b-9a6c-8d7e6f5a4b3c",
"blockchain_name": "ethereum",
"address": "0x1f9840a85d5af5bf1d1762f925bdaddc4201f984",
"project_name": "uniswap",
"contract_name": "UniswapToken",
"status": "pending",
"submission_type": "new",
"created_at": "2026-09-10T11:04:18.724658Z",
"updated_at": "2026-09-10T11:04:18.724658Z",
"idempotency_key": "uniswap-token/ethereum/1"
}
],
"total": 1
}
```
## OpenAPI
````yaml GET /v1/contracts/submissions
openapi: 3.0.1
info:
contact: {}
description: Dune API
title: DuneAPI
version: '1.0'
servers:
- url: https://api.dune.com/api
security: []
paths:
/v1/contracts/submissions:
get:
summary: List contract submissions
description: >-
List the contract decoding submissions made by the authenticated
account, newest first, with optional filters. Use this to track the
status of submissions made via POST /v1/contracts/decode. Page with
limit and the next_cursor returned by the previous response.
parameters:
- description: API Key for the service
in: header
name: X-Dune-Api-Key
required: true
schema:
type: string
- description: API Key, alternative to using the HTTP header X-Dune-Api-Key
in: query
name: api_key
schema:
type: string
- description: Filter by blockchain, e.g. ethereum
in: query
name: blockchain_name
schema:
type: string
- description: Filter by contract address
in: query
name: address
schema:
type: string
- description: Filter by project (namespace) name
in: query
name: project_name
schema:
type: string
- description: Filter by contract name
in: query
name: contract_name
schema:
type: string
- description: Filter by submission status
in: query
name: status
schema:
enum:
- pending
- approved
- rejected
- processed
- in_progress
- cancelled
- needs_manual_review
type: string
- description: Maximum number of submissions to return (default 50, max 250)
in: query
name: limit
schema:
type: integer
- description: >-
Opaque cursor for pagination. Use the value provided on a previous
response under next_cursor
in: query
name: cursor
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/models.ListContractSubmissionsResponse'
description: OK
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/models.Error400'
description: Bad Request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/models.Error401'
description: Unauthorized
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/models.Error403'
description: Forbidden
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/models.Error500'
description: Internal Server Error
components:
schemas:
models.ListContractSubmissionsResponse:
properties:
next_cursor:
description: >-
NextCursor is set when more submissions exist; pass it as the cursor
query parameter.
type: string
submissions:
items:
$ref: '#/components/schemas/models.ContractSubmissionSummary'
type: array
total:
type: integer
type: object
models.Error400:
properties:
error:
example: Bad Request
type: string
type: object
models.Error401:
properties:
error:
example: Invalid API Key
type: string
type: object
models.Error403:
properties:
error:
example: >-
Not allowed to execute query. Query is archived, unsaved or not
enough permissions
type: string
type: object
models.Error500:
properties:
error:
example: Internal error
type: string
type: object
models.ContractSubmissionSummary:
properties:
address:
type: string
blockchain_name:
example: ethereum
type: string
comment:
type: string
contract_name:
type: string
created_at:
example: '2024-12-20T11:04:18.724658237Z'
type: string
id:
type: string
idempotency_key:
type: string
project_name:
type: string
status:
enum:
- pending
- approved
- rejected
- processed
- in_progress
- cancelled
- needs_manual_review
type: string
submission_type:
enum:
- new
- upgrade
- rename
- delete
- other
type: string
updated_at:
example: '2024-12-20T11:04:18.724658237Z'
type: string
type: object
````