Retrieving app and event information

Page last updated:

This topic explains how to query the Cloud Controller API (CAPI) to retrieve current information about apps and events.

Target and log in

To perform the procedures in this topic, you must authenticate to your Cloud Controller. There are two ways of doing this:

• Run curl commands that include the Cloud Controller endpoint and pass in your authorization token each time with the -H flag.

• Run cf curl commands without including the endpoint or token. To do this, you must first use the Cloud Controller Command-Line Interface (cf CLI) to target the endpoint of your Cloud Controller and log in, as follows:

  1. Target the endpoint of your Cloud Controller:

     $ cf api api.YOUR-SYSTEM-DOMAIN

  2. Log in as admin or as an Org Manager or Org Auditor for the org you want to obtain information about.

     $ cf login -u admin
     API endpoint:  api.YOUR-SYSTEM-DOMAIN
     Email: user@example.com
     Password:
     Authenticating...
     OK
     ...
     Targeted org  YOUR-ORG
     Targeted space  development
     API endpoint:    https://api.YOUR-SYSTEM-DOMAIN (API version:  2.52.0)
     User:            user@example.com
     Org:             YOUR-ORG
     Space:           development
     

     If you do not have the cf CLI installed, see the Installing the cf CLI topic

Obtain app information

You can obtain the following app information.

All apps

Use the apps endpoint to retrieve information about all of your apps:

$ cf curl /v2/apps
{
 "total_results": 2,
 "total_pages": 1,
 "prev_url": null,
 "next_url": null,
 "resources": [
    {
        "metadata": {
           "guid": "acf2ce33-ee92-54TY-9adb-55a596a8dcba",
           "url": "/v2/apps/acf2ce33-ee92-54TY-9adb-55a596a8dcba",
           "created_at": "2016-02-06T17:40:31Z",
           "updated_at": "2016-02-06T18:09:17Z"
        },
        "entity": {
           "name": "YOUR-APP",
 [...]
           "space_url": "/v2/spaces/a0205ae0-a691-4667-92bc-0d0dd712b6d3",
           "stack_url": "/v2/stacks/86205f38-84fc-4bc2-b2b8-af7f55669f04",
           "routes_url": "/v2/apps/acf2ce33-ee92-54TY-9adb-55a596a8dcba/routes",
           "events_url": "/v2/apps/acf2ce33-ee92-54TY-9adb-55a596a8dcba/events",
           "service_bindings_url": "/v2/apps/acf2ce33-ee92-54TY-9adb-55a596a8dcba/service_bindings",
          "route_mappings_url": "/v2/apps/acf2ce33-ee92-54TY-9adb-55a596a8dcba/route_mappings"
           }
        },
    {
        "metadata": {
           "guid": "79bb58cc-3737-43be-ac70-39a2843b5178",
           "url": "/v2/apps/79bb58cc-3737-4540-ac70-39a2843b5178",
           "created_at": "2016-02-15T23:25:47Z",
           "updated_at": "2016-03-12T21:54:59Z"
        },
        "entity": {
           "name": "ANOTHER-APP",
[...]
           "space_url": "/v2/spaces/a0205ae0-a691-4667-92bc-0d0dd712b6d3",
           "stack_url": "/v2/stacks/86205f38-84fc-4bc2-b2b8-af7f55669f04",
           "routes_url": "/v2/apps/79bb58cc-3737-4540-ac70-39a2843b5178/routes",
           "events_url": "/v2/apps/79bb58cc-3737-4540-ac70-39a2843b5178/events",
           "service_bindings_url": "/v2/apps/79bb58cc-3737-4540-ac70-39a2843b5178/service_bindings",
           "route_mappings_url": "/v2/apps/79bb58cc-3737-4540-ac70-39a2843b5178/route_mappings"
         }
      }
   ]
}

The output of this command provides the URL endpoints for each app, within the metadata: url section. You can use these app-specific endpoints to retrieve more information about that app. In the example above, the endpoints for the two apps are /v2/apps/acf2ce33-ee92-54TY-9adb-55a596a8dcba and /v2/apps/79bb58cc-3737-4540-ac70-39a2843b5178.

App summary

Use the summary endpoint under each app-specific URL to retrieve the instances and any bound services for that app:

$ cf curl /v2/apps/acf2ce75-ee92-4bb6-9adb-55a596a8dcba/summary
{
       "guid": "acf2ce75-ee92-4bb6-9adb-55a596a8dcba",
   "name": "YOUR-APP",
   "routes": [
   {
      "guid": "7421b6af-75cb-4334-a862-bc5e1ababfe6",
      "host": "YOUR-APP",
      "path": "",
      "domain": {
         "guid": "fb6bd89f-2ed9-49d4-9ad1-97951a573135",
         "name": "YOUR-SYSTEM-DOMAIN.io"
     }
  }
],
  "running_instances": 5,
  "services": [
     {
        "guid": "b9cdr456-3c61-4f8a-a307-9b4ty836fb2e",
        "name": "YOUR-APP-db",
        "bound_app_count": 1,
        "last_operation": {
           "type": "create",
           "state": "succeeded",
           "description": "",
           "updated_at": null,
           "created_at": "2016-02-05T04:58:46Z"
     },
        "dashboard_url": "https://cloudfoundry.appdirect.com/api/custom/cloudfoundry/v2/sso/start?serviceUuid=b5cASDF-3c61-4f8a-a307-9bf85j45fb2e",
        "service_plan": {
           "guid": "fbcec3af-3e8d-4ee7-adfe-3f12a137ed66",
           "name": "turtle",
           "service": {
              "guid": "34dbc753-34ed-4cf1-9a87-a255dfca5339b",
              "label": "elephantsql",
              "provider": null,
              "version": null
[...]

To view the app_usages report that covers app usage within an org during a period of time, see List all app usage events in the Cloud Foundry API documentation.

Events

Use the events endpoint to retrieve information about app events.

For more information, see the Audit events topic and List all events in the Cloud Foundry API documentation.

App usage events

Use the app-usage-events endpoint to retrieve information about app usage events.

For more information, see the Usage events and billing topic and List all app usage events in the Cloud Foundry API documentation.