> ## Documentation Index
> Fetch the complete documentation index at: https://docs.n-3.co.uk/llms.txt
> Use this file to discover all available pages before exploring further.

# Worked Examples

> Copy-paste curl examples for common Data API calls

All examples assume your key is available as an environment variable:

```bash theme={null}
export N3_DATA_KEY="n3_data_xxxxxxxxxxxxxxxxxxxxxxxx"
export N3_DATA_URL="https://data.n-3.co.uk"
```

## Check your key status (free)

Confirm your key works, see its scopes, and check your remaining quota — this call never consumes quota:

```bash theme={null}
curl -s "${N3_DATA_URL}/data/quota" \
  -H "x-api-key: ${N3_DATA_KEY}" | jq
```

```json theme={null}
{
  "api_key_id": "0b2f6c1e-9a44-4c1d-8f3a-2f9d1c5e7a10",
  "environment_id": "42",
  "scopes": ["data:projects", "data:benchmarks", "data:reports"],
  "quota": {
    "used": 1240,
    "limit": 10000,
    "remaining": 8760,
    "resets_at": "2026-08-01T00:00:00.000Z",
    "period": "MONTH"
  },
  "throttle": { "rate_limit_per_second": 10, "burst_limit": 20 }
}
```

## List projects

First page of 25 projects, in-progress only:

```bash theme={null}
curl -s "${N3_DATA_URL}/data/projects?limit=25&offset=0&status=IN_PROGRESS" \
  -H "x-api-key: ${N3_DATA_KEY}" | jq
```

Page through the full list using `pagination.total`:

```bash theme={null}
# Second page
curl -s "${N3_DATA_URL}/data/projects?limit=25&offset=25" \
  -H "x-api-key: ${N3_DATA_KEY}" | jq '.pagination'
```

```json theme={null}
{ "limit": 25, "offset": 25, "total": 173 }
```

Extract just names and references:

```bash theme={null}
curl -s "${N3_DATA_URL}/data/projects?limit=200" \
  -H "x-api-key: ${N3_DATA_KEY}" \
  | jq -r '.items[] | "\(.project_reference)\t\(.name)"'
```

## Get a single project

```bash theme={null}
curl -s "${N3_DATA_URL}/data/projects/1042" \
  -H "x-api-key: ${N3_DATA_KEY}" | jq
```

A project id from another environment (or a non-existent id) returns 404:

```json theme={null}
{
  "message": "Project not found",
  "error": "Not Found",
  "statusCode": 404
}
```

## Project risk assessments and appraisals

```bash theme={null}
# Initial risk assessments (newest first)
curl -s "${N3_DATA_URL}/data/projects/1042/risk-assessments" \
  -H "x-api-key: ${N3_DATA_KEY}" | jq

# Development appraisal lines
curl -s "${N3_DATA_URL}/data/projects/1042/appraisals" \
  -H "x-api-key: ${N3_DATA_KEY}" | jq
```

## Benchmarks for one project

```bash theme={null}
curl -s "${N3_DATA_URL}/data/benchmarks?projectId=1042" \
  -H "x-api-key: ${N3_DATA_KEY}" | jq '.items[] | {id, type, model_value}'
```

## Reports

```bash theme={null}
# Metadata list
curl -s "${N3_DATA_URL}/data/reports?limit=10" \
  -H "x-api-key: ${N3_DATA_KEY}" | jq

# Detail with risk statuses
curl -s "${N3_DATA_URL}/data/reports/922" \
  -H "x-api-key: ${N3_DATA_KEY}" | jq '.risk_statuses'
```

## Community analytics (requires `data:community`)

```bash theme={null}
curl -s "${N3_DATA_URL}/data/community/analytics" \
  -H "x-api-key: ${N3_DATA_KEY}" | jq
```

Without the scope you receive 403:

```json theme={null}
{
  "message": "This API key does not have the required scope(s): data:community",
  "error": "Forbidden",
  "statusCode": 403
}
```

## Inspecting rate-limit headers

Use `-D -` to print response headers alongside the body:

```bash theme={null}
curl -s -D - "${N3_DATA_URL}/data/projects?limit=1" \
  -H "x-api-key: ${N3_DATA_KEY}" -o /dev/null
```

```text theme={null}
HTTP/1.1 200 OK
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 9
X-Quota-Limit: 10000
X-Quota-Remaining: 8759
X-Quota-Resets-At: 2026-08-01T00:00:00.000Z
```

See [Rate limits & quotas](/api-reference/data-api/rate-limits) for a full worked retry script.