Reports

Usage reports

List organization reports

get

Authorizations

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')

Path parameters

organizationIdstring · uuidRequired

The ID of the organization.

Query parameters

limitinteger · min: 1 · max: 100Optional

Limits the number of results to return

Default: 10

pageTokenstring · max: 8000Optional

Pagination token that keeps of track of the current position in the list

reversebooleanOptional

Order in which to retrieve the results

Default: false

Responses

200

application/json

get

/organizations/{organizationId}/reports

GET /organizations/{organizationId}/reports HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*

200

{
  "results": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "from": "2026-01-29",
      "productName": "text",
      "to": "2026-01-29",
      "createdAt": "2026-01-29T00:01:43.638Z",
      "productId": "123e4567-e89b-12d3-a456-426614174000",
      "createdBy": "123e4567-e89b-12d3-a456-426614174000",
      "organizationId": "123e4567-e89b-12d3-a456-426614174000",
      "rawKey": "text",
      "enrichedKey": "text",
      "status": "pending",
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "reportType": "itemised"
    }
  ]
}

curl -X GET "https://api.bird.com/organizations/{organizationId}/reports" \
 -H "Content-Type: application/json" \
 -H "Authorization: AccessKey abcd"

{
  "results": [
    {
      "id": "b657e211-a13c-58f0-85cb-508f622a502a",
      "reportType": "itemised",
      "organizationId": "organizationId",
      "productId": "productId",
      "productName": "cd03ae6e-90f8-4aa0-aba4-c1190acaf2bd",
      "createdBy": "createdBy",
      "rawKey": "rawKey.csv",
      "enrichedKey": "enrichedKey.csv.zip",
      "from": "2025-08-01",
      "to": "2025-08-31",
      "status": "complete",
      "createdAt": "2025-09-15T10:53:09.156Z",
      "metadata": null
    }
  ]
}

Create itemised report for organization and product

post

Authorizations

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')

Path parameters

organizationIdstring · uuidRequired

The ID of the organization.

Body

request to generate an itemised report

productIdstring · uuidRequired

ID of the product to generate report for

fromstring · dateRequired

Start date of the report period

tostring · dateRequired

End date of the report period

Responses

201

Created

application/json

404

The requested resource does not exist

application/json

422

The requested resource does not exist

application/json

post

/organizations/{organizationId}/reports

POST /organizations/{organizationId}/reports HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 90

{
  "productId": "123e4567-e89b-12d3-a456-426614174000",
  "from": "2026-01-29",
  "to": "2026-01-29"
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "from": "2026-01-29",
  "productName": "text",
  "to": "2026-01-29",
  "createdAt": "2026-01-29T00:01:43.638Z",
  "productId": "123e4567-e89b-12d3-a456-426614174000",
  "createdBy": "123e4567-e89b-12d3-a456-426614174000",
  "organizationId": "123e4567-e89b-12d3-a456-426614174000",
  "rawKey": "text",
  "enrichedKey": "text",
  "status": "pending",
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "reportType": "itemised"
}

curl -X POST "https://api.bird.com/organizations/{organizationId}/reports" \
 -H "Content-Type: application/json" \
 -H "Authorization: AccessKey abcd" \
 -d '{"productId": "9c31bfb6-d792-4a88-a0b9-904230230de5", "from": "2025-08-01", "to": "2025-08-10"}'

{
  "id": "150cb1d0-31f6-564b-af7f-b158b1c4b864",
  "reportType": "itemised",
  "organizationId": "organizationId",
  "productId": "9c31bfb6-d792-4a88-a0b9-904230230de5",
  "productName": "Alphanumeric",
  "createdBy": "da0a76a1-d0c7-4128-96d1-6951e6112d23",
  "rawKey": "feafd337-5d7e-42a5-a020-a4cbec8a2252/raw/feafd337-5d7e-42a5-a020-a4cbec8a2252_9c31bfb6-d792-4a88-a0b9-904230230de5_2025-08-01_2025-08-100.csv",
  "enrichedKey": "",
  "from": "2025-08-01",
  "to": "2025-08-10",
  "status": "pending",
  "createdAt": "2025-09-15T11:44:10.011Z",
  "metadata": null
}

ProductName

ProductId

abd21841-400c-4d1a-8322-51929abe668c

alphanumeric

9c31bfb6-d792-4a88-a0b9-904230230de5

chat

a59a938c-ada8-4100-8834-c541798fcb48

contact-lookup

49f682ae-6e30-440e-b86e-7d9171d0b35a

contacts

82fff5bd-e147-4fcc-a8c9-760adfbea58b

2a1b4126-2a2d-4dcc-bac1-9ec7fa632394

facebook

9728f45c-2686-4f20-b721-3ba98d33f5c0

flows

b815c4f7-a3be-465d-a5e6-2e3c05a10c23

inbox

6f44ba37-30b7-40d8-b8b0-c613d6b06ef4

instagram

2c384c4d-bc72-4b5e-8ef7-2c020a6538d7

journeys

67f75d99-9b64-46ba-958b-ad2a7629d850

line

1b240f93-cf07-4edf-9866-571d008d603f

mms

e88a8f43-d2ff-4ae6-9bb2-f4d00ff4b1e1

mms10dlc

a7d6fca8-96a6-4b2a-8993-d537a5ffeb7d

numbers

cd03ae6e-90f8-4aa0-aba4-c1190acaf2bd

shortcode

9e110353-70fb-4a89-bbbc-57b785c36b20

sms

ba676254-3771-448e-b499-fddab7182ccb

sms10dlc

856bdb66-2c5a-4c02-a332-27dadffbc502

cd570663-b355-4f38-8766-1d25ea106bbe

voice

70520167-460d-41ac-bf99-04eb26517814

0177585d-27cf-45f3-b43f-fdd8cb2dcce6

Create different report for organization and product by type

post

Authorizations

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')

Path parameters

organizationIdstring · uuidRequired

The ID of the organization.

reportTypestring · enumRequired

Filter organization bundles by status

Possible values:

Body

Responses

201

Created

application/json

404

The requested resource does not exist

application/json

422

The requested resource does not exist

application/json

post

/organizations/{organizationId}/reports/{reportType}

POST /organizations/{organizationId}/reports/{reportType} HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 90

{
  "productId": "123e4567-e89b-12d3-a456-426614174000",
  "from": "2026-01-29",
  "to": "2026-01-29"
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "from": "2026-01-29",
  "productName": "text",
  "to": "2026-01-29",
  "createdAt": "2026-01-29T00:01:43.638Z",
  "productId": "123e4567-e89b-12d3-a456-426614174000",
  "createdBy": "123e4567-e89b-12d3-a456-426614174000",
  "organizationId": "123e4567-e89b-12d3-a456-426614174000",
  "rawKey": "text",
  "enrichedKey": "text",
  "status": "pending",
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "reportType": "itemised"
}

curl -X POST "https://api.bird.com/organizations/{organizationId}/reports/aggregated" \
 -H "Content-Type: application/json" \
 -H "Authorization: AccessKey abcd" \
 -d '{"productId": "ba676254-3771-448e-b499-fddab7182ccb", "from": "2025-08-01", "to": "2025-08-31", "periodAggregation": "day"}'

{
  "id": "5338f834-ffbd-557c-bbed-c33f1c785d71",
  "reportType": "aggregated",
  "organizationId": "organizationId",
  "productId": "ba676254-3771-448e-b499-fddab7182ccb",
  "productName": "SMS Channel",
  "createdBy": "da0a76a1-d0c7-4128-96d1-6951e6112d23",
  "rawKey": "acb8572c-5432-4147-8c4b-aedb238702d4/raw/agg_prd_usg_acb8572c-5432-4147-8c4b-aedb238702d4_ba676254-3771-448e-b499-fddab7182ccb__2025-08-01_2025-08-310.csv",
  "enrichedKey": "",
  "from": "2025-08-01",
  "to": "2025-08-31",
  "status": "pending",
  "createdAt": "2025-09-15T12:56:57.44Z",
  "metadata": {
    "periodAggregation": "day",
    "units": null
  }
}

Download report csv file

get

Authorizations

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')

Path parameters

organizationIdstring · uuidRequired

The ID of the organization.

reportIdstring · uuidRequired

The ID of a Report.

Responses

200

Responsestring · binary

400

The requested resource does not exist

application/json

404

The requested resource does not exist

application/json

get

/organizations/{organizationId}/reports/{reportId}

GET /organizations/{organizationId}/reports/{reportId} HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*

binary

curl -X GET "https://api.bird.com/organizations/organizationId/reports/61e9b0a8-b69d-5844-8722-0f9e844af813" \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey abcd" \
-o downloadreport.zip

Last updated 4 months ago

Was this helpful?

hashtagList organization reports

hashtagCreate itemised report for organization and product

hashtagCreate different report for organization and product by type

hashtagDownload report csv file

List organization reports

Create itemised report for organization and product

Create different report for organization and product by type

Download report csv file